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KMBEDDED WF.R SERVER 



PCT/US97/13817 



rOPYRTHHT NOTICE 

The tables attached to the disclosure of this patent contain material that is subject to 
copyright protection. The copyright owner has no objection to the facsimile reproduction by 
anyone of the patent document or the patent disclosure, as it appears in the Patent and Trademark 
Office patent file or records, but otherwise reserves all copyright rights whatsoever. 

TABLES 

Table A is a functional specification of the Agranat Systems, Inc. Em Web™ product; and 
Table B is a source code listing in the C programming language of header files defining 

data structures representing an archive of content as used by the EmWeb''"" product. 

The noted tables are provided to show an example of a particular embodiment of the 

invention incorporating features thereof which are described in detail below. 

r pnSS-REFER FNrF TO RELATED APPLICATION 

Priority is claimed under 35 U.S.C. §n9(e) to the inventors' Provisional U.S. Patent 
Application Serial No. 08/023.373, entitled EXTENDED LANGUAGE COMPILER AND RUN 
TIME SERVER, filed August 8, 1996, now pending. The inventors' above-identified provisional 
U.S. patent application is incorporated herein by reference. 

L Field of the Invention 

The present invention relates generally to graphical user interfaces (GUIs), i.e. user 
interfaces in which information can be presented in both textual form and graphical form. More 
particularly, the invention relates to GUIs used to control, manage, configure, monitor and 
diagnose software and hardware applications, devices and equipment using a Worid- Wide- Web 
client/server communications model. Yet more particularly, the invention relates to methods and 
apparatus for developing and using such GUIs based on a Worid- Wide- Web client/server 
communications model. 
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2. Related Art 

Many modem communications, entertainment and other electronic devices require or 
could benefit from improved local or remote control, management, configuration, monitoring 
and diagnosing. It is common for such devices to be controlled by a software application 
program specifically written for each device. The design of such a device includes any hardware 
and operating environment software needed to support the application, which is then referred to 
as an embedded application, because it is embedded within the device. Embedded application 
programs are generally written in a high-level programming language such as C, etc., 
referred to herein as a native application programming language. Other languages suitable to 
particular uses may also be employed. The application program communicates with users 
through a user interface, generally written in the same high-level language as the application. 

The representation of an application in a native application programming language is 
referred to as the application program source code. A corresponding representation which can be 
executed on a processor is referred to as an executable image. 

Before an application written in a high-level language can be executed it must be 
compiled and linked to transform the application source code into an executable image. A 
compiler receives as an input a file containing the application source code and produces as an 
output a file in a format referred to as object code. Finally, one or more object code files are 
linked to form the executable image. Linking resolves references an object module may make 
outside of that object module, such as addresses, symbols or functions defined elsewhere. 

Source code may also define arrangements by which data can be stored in memory and 
conveniently referred to symbolically. Such defined arrangements are referred to as data 
structures because they represent the physical arrangement of data within memory, i.e., the 
structure into which the data is organized. 

Most commonly, remote control, management, configuration, monitoring and diagnosing 
applications employ unique proprietary user interfaces integrated with the application software 
and embedded into the device. Frequently these user interfaces present and receive information 
in text form only. Moreover, they are not portable, generally being designed to operate on a 
specific platform, i.e., combination of hardware and software. The devices for which control, 
management, configuration and diagnosing are desired have only limited run-time resources 
available, such as memory and long-term storage space. Proprietary interfaces are frequently 
designed with such limitations to data presentation, data acquisition and portability because of 
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the development costs incurred in providing such features and in order to keep the size and run- 
time resource requirements of the user interface to a minimum. Since each user interface tends to 
be unique to the particular remote control, management, configuration, monitoring or diagnosing 
function desired, as well as unique to the operating system, application and hardware platform 
upon which these operations are performed, significant lime and/or other resources may be 
expended in development. Graphics handling and portability have therefore been considered 
luxuries too expensive for most applications. 

However, as the range of products available requiring control, management, 
configuration, monitoring or diagnosing increase, such fonner luxuries as graphical presentation 
and portability of the interface from platform to platform have migrated from the category of 
luxuries to that of necessities. It is well known that information presented graphically is more 
quickly and easily assimilated than the same information presented as text. It is also well known 
that a consistent user interface presented by a variety of platforms is more likely to be understood 
and property used than unique proprietary user interfaces presented by each individual platform. 
Therefore, portable GUIs with low run-time resource requirements are highly desirable. 

With the growing popularity and expansion of the Internet, one extremely popular public 
network for communications between computer systems, and development of the Worid- Wide- 
Web communication and presentation model, a new paradigm for commxinication of information 
has emerged. 

The Worid- Wide- Web and similar private architectures such as internal corporate LANs, 
provide a "web" of intercoimected document objects. On the Worid- Wide- Web, these document 
objects are located on various sites on the global Internet. The World- Wide- Web is also 
described in "The Worid-Wide Web, " by T. Bemers-Lee, R. Cailliau, A. Luotonen, H. F. 
Nielsen, and A. Secret, Communications of the ACM^ 37 (8), pp. 76-82, August 1994, and in 
"Worid Wide Web: The Information Universe," by Bemers-Lee, T., et al., in Electronic 
Ngtworkine; Research, Applications and Policy> Vol. l, No. 2, Meckler, Westport, Conn., Spring 
1992. On the Internet, the Worid- Wide-Web is a collection of documents (i.e., content), client 
software (i.e., browsers) and server software (i.e., servers) which cooperate to present and receive 
information from users. The World -Wide- Web is also used to cormect users through the content 
to a variety of databases and services from which information may be obtained. However, except 
as explained below, the Worid- Wide- Web is based principally on static information contained in 
the content documents available to the browsers through the servers. Such a limitation would 
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make the World- Wide- Web paradigm useless as a GUI which must present dynamic information 
generated by a device or application. 

The World-Wide- Web communications paradigm is based on a conventional client-server 
model. Content is held in documents accessible to servers. Clients can request, through an 
5 interconnect system, documents which are then served to the clients through the interconnect 
system. The client software is responsible for interpreting the contents of the document served, 
if necessary. 

Among the types of document objects in a "web" are documents and scripts. Documents 
in the World-Wide- Web may contain text, images, video, sound or other information sought to 

10 be presented, in undetermined formats known to browsers or extensions used with browsers. The 
presentation obtained or other actions performed when a browser requests a document from a 
server is usually determined by text contained in a document which is written in Hypertext Mark- 
up Language (HTML). HTML is described in HvPcrText Markup Language Specification - 2.0 . 
by T. Bemers-Lee and D. Connolly, RPC 1866, proposed standard, November 1995, and in 

15 "Worid Wide Web & HTML," by Douglas C. McArthur, in Dr. Dobbs JoumaL December 1994, 
pp. 1 8-20, 22, 24, 26 and 86. HTML documents stored as such are generally static, that is, the 
contents do not change over time except when the document is manually modified. Scripts are 
programs that can generate HTML documents when executed. 

HTML is one of a family of computer languages referred to as mark-up languages. 

20 Mark-up languages are computer languages which describe how to display, print, etc. a text 

document in a device-independent way. The description takes the form of textual tags indicating 
a format to be applied or other action to be taken relative to document text. The tags are usually 
unique character strings having defmed meanings in the mark-up language. Tags are described 
in greater detail, below. 

25 HTML is used in the World- Wide- Web because it is designed for writing hypertext 

documents. The formal definition is that HTML documents are Standard Generalized Markup 
Language (SGML) documents that conform to a particular Document Type Definition (DTD). 
An HTML document includes a hierarchical set of markup elements, where most elements have 
a start tag, followed by content, followed by an end tag. The content is a combination of text and 

30 nested markup elements. Tags are enclosed in angle brackets ('<' and '>') and indicate how the 
document is structured and how to display the document, as well as destinations and labels for 
hypertext links. There are tags for markup elements such as titles, headers, text attributes such as 
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bold and italic, lists, paragraph boundaries, links to other documents or other parts of the same 
document, in-line graphic images, and many other features. 
For example, here are several lines of HTML: 

Some words are <B>bold<;/B>, others arc <I>italic<yi>. Here we start a new 
5 paragraph. <P> Here's a link to 

the <A HREF="http;//www.agranatxom">Agranat Systems, Inc.</A> home 
page. 

This sample document is a hypertext document because it contains a "link" to another 
10 document, as provided by the "HREF-." The format of this link will be described below. A 
hypertext document may also have a link to other parts of the same document. Linked 
documents may generally be located anywhere on the Internet. When a user is viewing the 
document using a client program called a Web browser (described below), the links are displayed 
as highlighted words or phrases. For example, using a Web browser, the sample document above 
15 would be displayed on the user's screen as follows: 

Some words are bold, others are italic. Here we start a new paragraph. 
Here's a link to A granat Systems. Inc. home page. 
In the Web browser, the link may be selected, for example by clicking on the highlighted 
area with a mouse. Selecting a link will cause the associated document to be displayed. Thus, 
20 clicking on the highlighted text "Agranat Systems, Inc." would display that home page. 

Although a browser can be used to directly request images, video, sound, etc. from a 
server, more usually an HTML document which controls the presentation of information served 
to the browser by the server is requested. However, except as noted below, the contents of an 
HTML file are static, i.e., the browser can only present a passive snapshot of the contents at the 
25 time the document is served. In order to present dynamic information, i.e., generated by an 
application or device, or obtain from the user data which has been inserted into an HTML- 
generated form, conventional World- Wide- Web servers use a "raw" interface, such as the 
common gateway interface (CGI), explained below, HTML provides no mechanism for 
presenting dynamic information generated by an application or device, except through a raw 
30 interface, such as the CGI. Regarding obtaining data from the user for use by the application or 
device, although standard HTML provides a set of tags which implement a convenient 
mechanism for serving interactive forms to the browser, complete with text fields, check boxes 
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and pull-down menus, the CGI must be used to process submitted forms. Form processing is 
important to remote control, management, configuration, monitoring and diagnosing applications 
because forms processing is a convenient way to configure an application according to user input 
using the World -Wide- Web communications model. But, form processing using a CGI is 
5 extremely complex, as will be seen below, requiring an application designer to learn and 
implement an unfamiliar interface. A CGI is therefore not a suitable interface for rapid 
development and prototyping of new GUI capabilities. Moreover, a developer must then master 
a native application source code language (e.g., C, C-H-, etc.), HTML and the CGI, in order to 
develop a complete application along with its user interface. 
10 Models of the World- Wide- Web communications paradigm for static content and 

dynamic content are shown in Figs. 14 and 15, respectively. As shown in Fig. 14, a browser 
1401 makes a connection 1402 with a server 1403, which serves static content 1405 from a 
storage device 1407 to the browser 1401. In the case of dynamic content, shown in Fig. 1 5, the 
server 1403 passes control of the connection 1402 with the browser 1401 to an application 1 501 , 
15 through the CG! 1503. The application 1501 must maintain the connection 1402 with the 

browser 1401 and must pass control back to the server 1403 when service of the request which 
included dynamic content is complete. Furthermore, during service of a request which includes 
dynamic content, the application 1501 is responsible for functions normally performed by the 
server 1403, including maintaining the cormection 1402 with the browser 1401, generating 
20 headers in the server/browser transport protocol, generating all of the static and dynamic content 
elements, and parsing any form data returned by the user. Since use of the CGI 1 503 or other 
raw interface forces the application designer to do all of this work, applications 1501 to which 
forms are submitted are necessarily complex. 

In order to provide dynamic content to a browser, the World- Wide- Web has also evolved 
25 to include Java and other client side scripting languages, as welt as some server side scripting 
languages. However, these languages are interpreted by an interpreter built into the browser 
1401 or server 1403, slowing down the presentation of information so generated. In the case of 
client side scripting, the script does not have any direct access to the application or to application 
specific information. Therefore, in order to generate or receive application specific information 
30 using client side scripting, the CGI 1 503 or other raw interface must still be used. In the case of 
server side scripting, the server 1 403 must parse the content as it is served, looking for a script to 
be interpreted. The access which a script has to the application is limited by the definition of the 
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scripting language, rather than by an application software interface designed by the application 
designer. 

A server side script is an executable program, or a set of commands stored in a file, that 
can be run by a server program to produce an HTML document that is then returned to the Web 

5 browser. Typical script actions include ruiming library routines or other applications to get 
information from a file, a database or a device, or initiating a request to get information from 
another machine, or retrieving a document corresponding to a selected hypertext link. A script 
may be run on the Web server when, for example, the end user selects a particular hypertext link 
in the Web browser, or submits an HTML form request. Scripts are usually written in an 

10 interpreted language such as Basic, Practical Extraction and Report Language (Perl) or Tool 
Control Language (Tel) or one of the Unix operating system shell languages, but they also may 
be written in programming languages such as the "C" programming language and then compiled 
into an executable program. Programming in Tcl is described in more detail in Tel and the Tk 
Toolkit , by John K. Ousterhout, Addison- Wesley, Reading, MA, USA, 1 994. Perl is described 

1 5 in more detail in Programming Perl , by Larry Wall and Randal L. Schwartz, O'Reilly & 
Associates, Inc., Sebastopol, CA, USA, 1992. 

Each document object in a web has an identifier called a Universal Resource Identifier 
(URI). These identifiers are described in more detail in T, Bemers-Lee, "Universal Resource 
Identifiers in Worid-Wide-Web: A Unifying Syntax for the Expression of Names and Addresses 

20 of Objects on the. Network as used in the Worid-Wide Web ." RFC 1 630, CERN, June 1 994; and 
T. Bemers-Lee, L. Masinter, and M. McCahill, " Uniform Resource Locators (URL^ ." RFC 1738, 
CERN, Xerox PARC, University of Miimesota, December 1994. A URI allows any object on 
the Internet to be referred to by name or address, such as in a link in an HTML document as 
shown above. There are two types of URIs: a Universal Resource Name (URN) and a Uniform 

25 Resource Locator (URL), A URN references an object by name within a given name space. The 
Internet community has not yet fully defined the syntax and usage of URNs, A URL references 
an object by defining an access algorithm using network protocols. An example URL is 
"http://www.agranat.com" A URL has the syntax "scheme: scheme_specific_components" where 
"scheme" identifies the access protocol (such as HTTP, FTP or GOPHER). For a 

30 scheme of HTTP, the URL may be of the form '•http://host:port/path?search" 

where 

"host" is the Internet domain name of the machine that supports the protocol; 
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"port" is the transmission control protocol (TCP) port number of the appropriate 

server (if different from the default); 

"path" is a scheme-specific identification of the object; and 

"search" contains optional parameters for querying the content of the object. 
URLs are also used by web servers and browsers on private computer systems or networks and 
not just the World- Wide- Web. 

A site, i.e. an organization having a computer connected to a network, that wishes to 
make documents available to network users is called a "Web site" and must run a "Web server" 
program to provide access to the documents. A Web server program is a computer program that 
allows a computer on the network to make documents available to the rest of the World-Wide- 
Web or a private web. The documents are often hypertext documents in the HTML language, 
but may be other types of document objects as well, as well as images, audio and video 
information. The information that is managed by the Web server includes hypertext documents 
that are stored on the server or are dynamically generated by scripts on the Web server. Several 
Web server software packages exist, such as the Conseil Europeen pour la Recherche Nucleaire 
(CERN, the European Laboratory for Particle Physics) server or the National Center for 
Supercomputing Applications (NCSA) server. Web servers have been implemented for several 
different platforms, including the Sun Sparc 1 1 workstation running the Unix operating system, 
and personal computers with the Intel Pentium processor running the Microsoft® MS-DOS 
operating system and the MicrosoftCg) Windows™ operating environment. 

Web servers also have a standard interface for running external programs, called the 
Common Gateway Interface (CGI). CGI is described in more detail in How To Set Up And 
Maintain A Wgb Sitg, by Lincoln D. Stein, Addison- Wesley, August 1995. A gateway is a 
program that handles incoming information requests and returns the appropriate document or 
generates a document dynamically. For example, a gateway might receive queries, look up the 
answer in an SQL database, and translate the response into a page of HTML so that the server 
can send the result to the client. A gateway program may be written in a language such as "C" or 
in a scripting language such as Perl or Tel or one of the Unix operating system shell languages. 
The CGI standard specifies how the script or application receives input and parameters, and 
specifies how any output should be formatted and returned to the server. 

A user (typically using a machine other than the machine used by the Web server) that 
wishes to access documents available on the network at a Web site must run a client program 
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called a "Web browser." The browser program allows the user to retrieve and display documents 
from Web servers. Some of the popular Web browser programs are: the Navigator browser from 
NetScape Communications Corp., of Mountain View, California; the Mosaic browser from the 
National Center for Supercomputing Applications (NCSA); the WinWeb browser, from 
Microelectronics and Computer Technology Corp. of Austin, Texas; and the Internet Explorer, 
from Microsoft Corporation of Redmond, Washington. Browsers exist for many platforms, 
including personal computers with the Intel Pentium processor running the Microsoft® MS-DOS 
operating system and the Microsoft® Windows™ environment, and Apple Macintosh personal 
computers. 

The Web server and the Web browser communicate using the Hypertext Transfer 
Protocol (HTTP),message protocol and the underlying transmission control protocol/internet 
protocol (TCP/IP) data transport protocol of the Internet. HTTP is described in Hypertext 
. TransfgrProtOg^^l-HTTF/1 0 , by T. Bemers-Lee, R. T. Fielding, H. Frystyk Nielsen, Internet 
Draft Document, October 14, 1995, and is currently in the standardization process. At this 
writing, the latest version is found in RFC Z068 which is a draft definition of HTTP/1. 1. In 
HTTP, the Web browser establishes a connection to a Web server and sends an HTTP request 
message to the server. In response to an HTTP request message, the Web server checks for 
authorization, performs any requested action and returns an HTTP response message containing 
an HTML documem resulting from the requested action, or an en-or message. The returtied 
■ HTML document may simply be a file stored on the Web server, or it may be created 
dynamically using a script called in response to the HTTP request message. For instance, to 
retrieve a document, a Web browser sends an HTTP request message to the indicated Web 
server, requesting a document by its URL. The Web server then retrieves the documem and 
returns it in an HTTP response message to the Web browser. If the document has hypertext 
links, then the user may again select a link to request that a new document be retrieved and 
displayed. As another example, a user may fill in a form requesting a database search, the Web 
browser will send an HTTP request message to the Web server including the name of the 
database to be searched and the search parameters and the URL of the search script. The Web 
server calls a program or script, passing in the search parameters. The program examines the 
parameters and attempts to answer the query, perhaps by sending a query to a database interface. 
When the program receives the results of the query, it constructs an HTML document that is 
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retumed to the Web server, which then sends it to the Web browser in an HTTP response 
message. 

Request messages in HTTP contain a "method name" indicating the type of action to be 
performed by the server, a URL indicating a target object (either document or script) on the Web 

5 server, and other control information. Response messages contain a status line, server 

infonnation, and possible data content. The Multipurpose Internet Mail Extensions (MIME) are 
a standardized way for describing the content of messages that are passed over a network. HTTP 
request and response messages use MIME header lines to indicate the format of the message. 
MIME is described in more detail in MIME (Mu hiourpose Internet Mail RxtensionsV 

1 0 Mechanisms for Specifying and Describing the Format of Intern et Message Bodies Internet RFC 
1 34 U June 1992. 

The request methods defmed in the HTTP/1 . 1 protocol include GET, POST. PUT. 
HEAD, DELETE, LINK, and UNLINK. PUT, DELETE, LINK and UNLINK are less 
commonly used. The request methods expected to be defmed in the final version of the 

1 5 HTTP/1 . 1 protocol include GET, POST, PUT, HEAD, DELETE, OPTIONS and TRACE. 
DELETE, PUT, OPTIONS and TRACE are expected to be less commonly used. All of the 
methods are described in more detail in the HTTP/1 .0 and HTTP/1.1 specifications cited above. 

Finally, a device or application using conventional World- Wide- Web technology must 
have access to a server. Conventional servers are large software packages which run on 

20 relatively large, resource-rich computer systems. These systems are resource-rich in terms of 
processing speed and power, long-term storage capacity, short-term storage capacity and 
operating system facilities. Conventional servers take advantage of these resources, for example, 
in how they store content source documents. For high-speed, convenient access to content, it is 
conventionally stored in a directory tree of bulky ASCII text files. Therefore, conventional 

25 World- Wide- Web technology cannot be used to implement a GUI in a relatively small, 
inexpensive, resource-poor device or application. 

The combination of the Web server and Web browser communicating using an HTTP 
protocol over a computer network is referred to herein as the World -Wide- Web communications 
paradigm. 



30 
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SUMMARY OF THK INVFNTION 

It is therefore an object of the present invention to provide an improved graphical user 
interface (GUI) for use in connection with remote control, management, configuration, 
monitoring and diagnosing fiinctions embedded in applications, devices and equipment. 
5 According to one aspect of the invention, there is provided a method for providing a 

graphical user interface having dynamic elements. The method begins by defining elements of 
the graphical user interface in at least one text document written in a mark-up language. Next, 
the method defines including at a location in the document a code tag containing a segment of 
application source code. The text document is then served to a client which interprets the mark- 
10 up language; and when the location is encountered, the client is served a sequence of characters 
derived from a result of executing a sequence of instructions represented by the segment of 
application source code. An embodiment of code tags illustrating their use is described in detail, 
later. 

According to another aspect of the invention, there is another method for providing a 

1 5 graphical user interface having dynamic elements. This method also defines elements of the 
graphical user interface in at least one text document written in a mark-up language. Included in 
the document is a string identified by prototype tags. The text document is served to a 
prototyping client which interprets the mark-up language but does not recognize and does not 
display the prototype tag, but does display the string. An embodiment of prototype tags 

20 illustrating their use is described in detail, later. 

According to yet another aspect of the invention, there is yet another method for 
providing a graphical user interface having dynamic elements. Elements of the graphical user 
interface are defined in at least one text document written in a mark-up language. Included at a 
location in the document is a code tag cont£uning a segment of application source code. Also 

25 included in the document is a string identified by prototype tags. The text document is compiled 
into a content source, which is subsequently decompiled into a replica of the text document. The 
replica of the text document is served to a client which interprets the mark-up language; and 
when the location is encountered in the replica, the client is served a character stream generated 
by executing the segment of application source code. 

30 Yet another aspect of the invention is a software product recorded on a medium. The 

software product includes a mark-up language compiler which can compile a mark-up language 
document into a data structure in a native application programming language, the compiler 



•i 
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recognizing one or more code tags which designate included text as a segment of apphcation 
source code to be saved in a file for compilation by a compiler of the native application 
programming language. 

Another aspect of the invention is a method for providing a graphical user interface 
5 having displayed forms for entry of data. The steps of this method include defining elements of 
the graphical user interface in at least one text document written in a mark-up language; naming 
in the document a data item requested of a user and used by an application written in a native 
application programming language; and compiling the text document into a content source 
including a data structure definition in the native application programming language for the 

10 named data item. 

Yet another aspect of the invention may be practiced in a computer-based apparatus for 
developing a graphical user interface for an application, the apparatus including an editor which 
can manipulate a document written in a mark-up language and a viewer which can display a 
document written in the mark-up language. The apparatus further includes a mark-up language 

15 compiler which recognizes a code tag containing a source code fragment in a native application 
source code language, the code tag not otherwise part of the mark-up language, the compiler 
producing as an output a representation in the native application source code language of the 
document, including a copy of the source code fragment. 

In accordance with another aspect of the invention, there is a method for developing and 

20 prototyping graphic user interfaces for an application. The method includes accessing an HTML 
file, encapsulating portions of said HTML and entering source code therein, producing a source 
module from said HTML with encapsulated portions, producing source code for a server, and 
cross compiling and linking said application, said source code module and said server thereby 
producing executable object code. 

25 The invention, according to another aspect thereof, may be a data structure fixed in a 

computer readable medium, the data sUiicture for use in a computer system including a client and 
a server in communication with each other. The data structure includes cross-compiled, stored 
and linked, HTML files with encapsulated portions containing executable code associated with ■ 
said application, server code, and application code, wherein said executable code is run when the 

30 HTML file is served thereby providing real time dynamic data associated with said application. 
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BRIEF DESCRIPTION OF T HE DRAW^iyr, ^ 
In the drawings, in which like reference numerals denote like elements: 
Fig. 1 is a block diagram of that aspect of the invention relating to development systems; 
Fig. 2 is a block diagram of that aspect of the invention relating to an embedded system; 
Fig. 3 is an HTML text fragment illustrating the use of an EMWEB_STRrNG tag; 
Fig. 4 is another HTML text fragment illustrating another use of an EM WEB STRING 

tag; 

Fig. 5 is an HTML text fragment illustrating the use of an EMWEBJNCLUDE tag; 
Fig. 6 is another HTML text fragment illustrating another use of an EM WEB INCLUDE 

tag; 

Fig. 7 is an HTML text fragment showing a use of the EMWEB_ITERATE attribute in 
connection with an EMWEB_STRING tag; 

Fig. 8 is an HTML text fragment showing a use of the EMWEBJTERATE attribute in 
connection with an EMWEB INCLUDE tag; 

Fig. 9 is an example of forms processing showing the relationship between the HTML 
source code for the form and the form output produced; 

Fig. 10 is a block diagram of the data structure which defines the header for the data.dat 
archive file; 

Fig. 11 is a state diagram of an embedded system illustrating dynamic content processing; 

Fig. 12 is a state diagram of an embedded system illustrating forms processing; 

Fig. 1 3 is a state diagram of an embedded system illustrating suspend/resume processing; 

Fig. 14 is a block diagram illustrating conventional World- Wide- Web communication of 
static content between a server and a client; and 

Fig. 15 is a block diagram illustrating conventional World- Wide- Web communication of 
dynamic content between a server and a client. 

DETATI.F.n TI ESCRIPTION 

The present invention will be better understood upon reading the following detailed 
description in connection with the figures to which it refers. 

Embodiments of various aspects of the invention are now described. First, a development 
environment is described in which application development and graphical user interface 
development are closely linked, yet require a low level of complexity compared to conventional 
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development of an application and GUI. Second, an operating environmem is described in which 
the application, a server and GUI are tightly coupled, compact and flexible. In the described 
system a GUI having portability, low run-time resource requirements and using any of a wide 
variety of systems available to a user as a universal front end, i.e. the point of contact with the 
5 user is software with which the user is already familiar. 

Development Environment 

Fig. 1 illustrates a development environment according to one aspect of the invention. 
Not all components of the environment are shown, but those shown are identified in the 

1 0 following discussion. 

Conventionally, an application development environment may include a source code 
editor, a compiler 101, a linker and a run-time environment in which to test and debug the 
appHcation. It is expected that development environments in accordance with the invention 
include those components of a conventional development environment which a developer may 

1 5 find useful for developing an application. In the case of embedded applications, i.e., applications 
included within a device or larger application, the run-time environment includes the device or 
application in which the application is embedded, or a simulation or emulation thereof 

The compiler 101 takes source code 103 generated using the source code editor or from 
other sources and produces object code 105, which is later linked to fom the executable image. 

20 In addition to the conventional elements noted above, the described embodiment of a 

development environment according to the invention includes an HTML compiler 107 whose 
output 109 is in the source code language of the application under development. In addition, the 
development environment may include an HTML editor, an HTTP-compatible server for 
communicating with client software, i.e., browsers, and an HTTP-compatible browser. 

25 The HTML editor is used to create and edit HTML documents 1 1 1 which define the look 

and feel of a GUI for the application. Numerous tools are now available for performing this task 
while requiring a minimal knowledge or no knowledge of HTML, for example, Microsoft* Front 
Page™. It is preferred that the HTML editor used permit entry of non-standard tags into the 
HTML document. 

30 As will be seen in fiirther detail, below, the server and browser are used to test a 

prototype GUI before it is fully integrated with the application or in the absence of the 
application. The browser should be capable of making a connection with the server using, for 
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example, a conventional connection protocol such as TCP/IP, as shown and described above in 
connection with Fig. 14. Other protocols or direct connections can also be used, as would be 
understood by those skilled in this art. While the browser and the server may be connected 
through a network such as the Internet, they need not be. For example, the server and client may 
5 run and connect on a single computer system. 

Application development proceeds substantially in a conventional maimer as known to 
software developers. The application development should include the design of a software 
interface through which data will be communicated into and out of the application. However, the 
software interface is not a GUI. Rather, the interface merely defmes how other software can 

10 communicate with the application. For example, the interface may be a collection of function 
calls and global symbols which other software can use to communicate with the application. The 
application should be written in a high level language such as C, C-H-, etc. The application can 
be tested by compiling and linking it with prototype code that provides or receives information 
through the software interface, exercising those features of the application. 

15 Meanwhile, a GUI for the application is designed as follows. The look and feel of the 

GUI are developed using the HTML editor, server and browser to create a set of content source 
documents 1 1 1 including at least one HTML document, which together deftne the look and feel 
of the GUI. This aspect of GUI development is conventional, proceeding as though the 
developer were developing a World- Wide- Web site. 

20 At locations in one or more HTML documents where data obtained fi-om the application 

is to be displayed, the author includes special tags, explained further below, which allow the 
HTML document to obtain from the application the required data, using the application software 
interface. 

The content source documents 1 1 1 are stored conventionally in the form of one or more 
25 directory trees 113. The directory tree 1 1 3 containing the content which defmes the GUI is then 
compiled using the HTML compiler 107, to produce an application source, code language output 
109 representing the content source documents in the directory tree. The source code elements 
109 produced from the content source documents 111 in the directory tree 113, source code for 
an HTTP compatible server (not shown) and the application source code 103 are compiled into 
30 object code 105 and linked to form an executable image. The server may be supplied in the form 
of an object code library, ready for linking into the finished executable image. The executable 
image thus formed ftiHy integrates the graphical user interface defmed using familiar tools of 
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World- Wide- Web content development with the control and other functions defined using 
conventional application development tools. 

In order to successfully perform the integration described above, the HTML compiler 1 07 
of the described embodiment of the invention, the Em Web'^^/compiler 1 07, recognizes a number 
5 of special extensions to HTML, The HTML extensions implemented by the EmWeb'^'^/compiler 
107, embodying aspects of the invention are described in detail in Table A, Section 3.2. Several 
of these extensions are described briefly here, to aid in understanding the invention. 

The EM WEB_STRING tag is an extension of HTML used to encapsulate a fragment of 
source code in the HTML dociunent. The source code will be executed by a system in which the 
10 application is embedded when the document is served to a browser (usually running on another 
system) and the location of the EMWEB_STRrNG tag is reached. The source code returns a 
character string that is inserted as is into the document at the location of the EMWEB_STRJNG 
tag. Examples of the use of the EMWEB_STRING tag are shown in Figs. 3 and 4. 

In the example of Fig. 3, the EMWEB_STRING tag 301 first defines using "C=" a 
1 5 boundary character 303 used to define the end 305 of the included source code. Immediately 
following the boundary character definition is a fragment of C code 307 which returns a pointer 
to a string representing one of three fax states. When served by an embedded application, this 
example HTML produces the text "NetFax State:" followed by "Sending", '^Receiving" or "Idle", 
depending on the value of the symbol GlobalFaxState. 
20 The example of Fig. 4 shows the use of EM WEB_STRING to output typed data whose 

type is defined by an attribute, EMWEB_TYPE 401. The EmWeb™/compiler uses this attribute 
401 to produce a source code output routine which converts the typed data found at the address 
returned 403 into a string for serving at the proper location in the document. 

A similar function is performed by the HTML extension, the EMWEB INCLUDE tag. 
25 Using this tag, standard parts of a GUI such as headers and footers common to multiple pages or 
windows of information need only be stored once. Header and footer files are referred to using 
the EMWEB_INCLUDE tag which inserts them at the location in each HTML content document 
where the tag is placed. In the described embodiment of the invention, the contents of the 
EMWEB_INCLUDE tag must resolve to a relative or absolute path name within the local 
30 directory tree of content. This can be done by specifying a local Universal Resource Locator 
(URL), which is how resources are located in the World- Wide- Web communications paradigm, 
or by including source code which returns a string representing such a local URL. An absolute 
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local URL takes the form "/path/filename", where "/path" is the full path from the root of the 
directory tree to the directory in which the file is located. A relative URL defines the location of 
a file relative to the directory in which the current, i.e., base, document is located and takes the 
form "path/filename". While the described embodiment requires resolution of the 
EMWEBJNCLUDE tag to a local URL, the invention is not so limited. In alternate 
embodiments, local and external URLs may be pemiitted or other limitations imposed. 
Examples of the use of the EMWEB_INCLUDE tag arc shown in Figs. 5 and 6. 

In the example of Fig. 5, a COMPONENT attribute 501 in an EMWEB^INCLUDE tag 
simply defines a local URL 503. 

In the more elaborate example of Fig. 6, a fragmem of source code 601 which produces a 
local URL 603 upon a defined condition 605 is used to generate a local URL at run time. 

The results to be returned by an EMWEB_STRING or EM WEB_INCLUDE tag can also 
be built up iteratively using repeated calls to the included sour<:e code. This is done using the 
EMWEB_ITERATE attribute, yet another extension to HTML. Examples of the use of 
EMWEB JTERATE are shown in Figs. 7 and 8. 

Fig. 7 shows an example of the EM WEB JTERATE attribute 701 used in connection 
with the EMWEB^STRING tag 703. The fragment of code 705 is executed repeatedly until a 
NULL is retumed. Thus, this HTML repeatedly executes the C source code fiagment to display 
the tray status of all trays in a system. 

Similarly, in Fig. 8, EMWEBJNCLUDE 801 and EM WEB JTERATE 803 are used to 
build a table of features for which content from other URLs 805 are to be displayed. When the 
table is complete, a NULL is retumed 807, terminating the iterations. 

Since the extensions to HTML described above allow the encapsulation of source code 
within an HTML document a mechanism with which to provide the encapsulated source code 
with required global definitions, header files, external declarations, etc. is also provided in the 
form of an EMWEB_HEAD tag. The EMWEB_HEAD tag specifies a source code component 
to be inserted in the source code output of the EmWeb™/compiler, outside of any defined 
function. Although it is preferred that the EMWEB_HEAD tag appears in the HTML file 
header, it may appear anywhere. The code generated by an EMWEB_HEAD tag is placed before 
any functions or other code defined within the HTML content source doctmients. 

As indicated above, the GUI may be prototyped using a conventional server and browser 
(see Fig. 14) to preview the HTML documents comprising the GUI. Therefore, it may be useful 
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to provide static content with which to preview the page, at locations where dynamic content will 
appear during use, but which does not appear in the compiied document. For example, it may be 
useful to include a prototyping value for content which is otherwise provided using the 
EMWEB STRING tag mechanism. Therefore, another extension to HTML recognized by the 

5 EmWebTM/compiler is the EM WEB_PROTO begin 309 and end 3 II tags, as shown in Fig. 3 . 
The EmWeb™/compiler removes these tags and everything between them when compiling the 
document, but the tags are ignored and the text between them is interpreted normally by a 
conventional browser viewing the HTML document either directly or via a conventional server. 
Conventional browsers recognize the tag due to its special syntax, e.g., being enclosed in and 

10 ">", but are designed to ignore and not display any tag for which the browser does not have a 
defmition. All EmWeb™/compiler HTML extensions are thus skipped over by conventional 
browsers. Thus, in the example of Fig. 3, the prototype page displays "NetFax State: Sending". 
Fig. 4 shows a similar use of EMWEB PROTO tags. 

Handling of HTML forms by the EmWeb™/compiler is now described in connection 

IS with Fig. 9. As seen in Fig. 9, an HTML form is defined substantially conventionally. Names 
used in the form are used in constructing symbol names used in the output source code produced 
by the EmWeb™/compiler. Therefore names should be valid symbol names in the source code 
language. 

Each element of a form definition is translated by the EmWeb'^^/compiler into a part of a 
20 corresponding data structure defined for that form. Forms data is moved into and out of the 
application by changing values of items in the data structure. 

Turning now to the example in Fig. 9, the relationship between the illustrated HTML 
form definition and the corresponding data structure is described. The form is given a unique 
name, using an EMWEB^NAME attribute in a FORM tag. The form name becomes part of the 
25 structure name, for easy reference and uniqueness. The form name will also be used to generate 
function names for functions which are called when the form is served and when the form is 
submitted. 

The structure generated is itself composed of two structures. The first holds values of 
each dynamic element of the form. The second holds a status flag indicating the status of the 
30 contents of a corresponding value. Thus, in the example of Fig. 9, a structure to hold values and 
status for the sysName INPUT and the Logging SELECTion is created. The value of sysName is 
a character string, while Logging is an enumerated type. 
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Two function prototypes are also generated. The actions to be performed by these 
functions must be defined by the developer. The Serve function is called when the form is 
served and can be used to supply default values, for example. The Submit function is called 
when the form is submitted, to update values in the data structure, for example. 
5 Currently, EmWeb™/compiler supports TEXT, PASSWORD, CHECKBOX, RADIO, 

IMAGE, HIDDEN, SUBMIT, RESET, SELECT and OPTION input fields. For detailed 
descriptions, see Table A, Section 3.2.5, In addition, the EmWeb™/compiler supports "typing" 
of TEXT input field data. That is, the EMWEB_TYPE attribute may be used to define a TEXT 
input field to contain various kinds of integers, a dotted IP address (i.e., an address of the form 

10 000.000.000.000), various other address formats, etc. A mapping of EM WEB TYPE values to 
C language types is formed in the table in Table A, Section 3.2.5.3. 

The EmWeb™/compiler has been described in terms of a generic application source code 
language. The current commercial embodiment of the EmWeb™/compiler assumes the 
application source code language to be C or a superset thereof, e.g., C++, However, the 

15 fimctionality described can be generalized to any application source code language which may be 
preferred for a particular application purpose. However, in order to more fully understand how 
the EmWeb^/compiler and HTML extensions described above cooperate to permit integration 
of an HTML defined GUI with an application defined in an application source code, it will be 
assumed, without loss of generality, that the application source code language is C or a superset 

20 thereof 

The EmWeb™/compiler produces a set of output files including a data.dat file containing 
the fixed data of a content archive, a code.c file containing the generated source code portions of 
an archive including portions defined in EMWEB^STRING, EMWEB_INCLUDE and 
EMWEB_HEAD tags and other source code generated by the EmWeb^/compiler, as well as 
25 proto.h and stubs.c files containing the definitions of C functions used for forms processing. The 
structure of these files is now described in connection with the data structure illustrated in Fig. 
10. 

The content archive file data.dat has a header structure as illustrated in Fig. 10. The data 
structure is accessed through an archive header 1001 which is a table of offsets or pointers to 
* 30 other parts of the archive. For example, there is a pointer 100 1 a to a compression dictionary 
1 003 for archives which include compressed documents. There is also a pointer 100 lb to a 
linked list of document headers i005, 1007 and 1009. Each document header 1005, 1007 and 
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1 009 is a table of offsets or pointers to various components of the document. For example, the 
document header includes a pointer 1005a to the URL 101 1 to which the document corresponds. 
There is also a pointer 1005b to a field 1013 giving the Muhipurpose Internet Mail Extension 
(MIME) type of the document. There are pointers 1005c and 1005d respectively to header nodes 
5 1015 and document nodes 1017, explained further below. Finally, there is a pointer 1 005e to a 
block of static compressed or uncompressed data 1019 representing the static portions of the 
document. 

The static data does not include any Em Web™ tags, i.e., the extensions to HTML 
discussed above and defined in detail in Table A. Rather, information concerning any Em Web™ 

10 tags used in the document appears in the document nodes structure. 

Each Em Web™ tag employed in a document is represented in that document's document 
nodes structure as follows. The location of the Em Web™ tag within an uncompressed data 
block or an uncompressed copy of a compressed data block is represented by an offset 101 7a 
relative to the uncompressed data. The type of tag is indicated by a type flag 1017b. A node 

15 may include a flag which indicates any attributes associated with the tag represented. For 

example, a node for a tag of type EM WEB_STRING may include a flag indicating the attribute 
EMWEB ITERATE. Finally, nodes include an index 1017c. In nodes defining form elements, 
the index holds a form number and element number uniquely identifying the element and form 
within the document. In nodes defining EMWEB STRING tags, the index is a reference to the 

20 instance of source code which should be executed at that point. As such, the index may be 
evaluated in an expression of a "switch*' statement in C, where each controlled statement of the 
"switch" statement is one source code fragment from one EMWEB STRING instance. 
Alternatively, the index may be a pointer or index into a table of source code fragments from 
EMWEB_STRING tags, which have been encapsulated as private functions. 

25 The data structure defined above provides a convenient way of transferring control as a 

document containing dynamic content is served. When a document is requested, the list of 
document nodes is obtained, to determine at what points control must be transferred to code 
segments which had been defined in the HTML source document. The document is then served 
using the data block defining the static elements of the document, until each document node is 

30 encountered. When each document node is encountered, control is transferred to the appropriate 
code segment. After the code segment completes execution, the static content which follows is 
served until the offset of the next dociunent node is encountered. 
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Header nodes permit the storage of document meta information, not otherwise handled, 
such as content language, e.g., English, Gennan, etc., cookie control, cache control or an e-tag 
giving a unique version number for a document, for example a 30-bit CRC value computed for 
the document. By avoiding having to put this information in the header of each document, 
significant space can be saved in the archive because not all documents require this information. 
Therefore, header nodes need only be stored for documents using this information. 

The data structure which represents the archive of content used by the 
EmWeb™/compiler embodiment of the invention is defined by the C source code contained in 
Table B. 



Run-time Environment 

Aspects of the invention related to the run-time environment and server are embodied in 
the EmWeb'^M/server as described in detail in Table A, Section 4. 

To a conventional browser implementing HTTP, die EmWeb'^"/server behaves 
conventionally. However, as shown in Fig. 2, the EmWeb™/server is fully integrated with the 
application and therefore has access to information about the application and device in which it is 
embedded. 

Operation of the EmWeb™/server with respect to presentation of dynamic content is now 
described in connection with.Fig. 11. 

Before the operations shown in Fig. 1 1 commence, one or more archives are loaded by 
the server. When each archive is loaded, the server generates a hash table using the archive 
header data structure to make documents easy to locate using URLs. 

First, the browser requests a document at a specified URL, using HTTP 1101. The 
EmWeb™/scrver acknowledges the request, in the conventional manner 1 103. The 
EmWebTM/server then uses the hash table of the archive header to locate the document requested 
and begin serving static data fi-om the document 1 105. When a document node is encountered, 
for example denoting the presence of an EMWEB_STRING tag, then the server passes control to 
the code fragment 1 107a of the application which had been included in the EMWEB_STRING 
tag 1 107. When the code firagment completes execution and returns some dynamic data 1 109, 
the Em Web™/server then serves that dynamic data to the browser 1111. The EmWebTw/server 
then resumes serving any static data remaining in the document 1113. This process continues 
until the entire document, including all dynamic elements has been served. 
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Run-time serving and submission of forms is now described in connection with Fig. 12. 
A brief inspection of Fig. 12 will show that form service and submission proceeds along similar 
lines to those for serving dynamic content. 

The browser first requests a URL using HTTP 1201 . When, during service of the 
5 contents of the URL requested, a form is encountered, service of the form and any HTML- 
defmed default values commences normally. The EmWeb™/server then makes a call to the 
application code 1203 to run a function 1203a which may substitute altemate default values 1205 
with which to fill in the form. The document served then is made to include the default values 
defined by the static HTML as modified by the application software 1207. Later, when the user 
10 submits the form, the browser performs a POST to the URL using HTTP 1209. The form data is 
returned to the application by a call 1211 made by the EmWeb^/server to a function 1211 which 
inserts the data returned in the form into the data structure defined therefor within the application 
code. The response 1213 is then served back to the browser 1215. 

Finally, it should be noted that there may be times when a request for dynamic content 
15 may require extended processing, unacceptably holding up or slowing down other operations 
performed by the application. In order to avoid such problems, the EmWeb™/server implements 
a suspend/resume protocol, as follows. The suspend/resume protocol exists within a context of a 
scheduler maintained and operated by the server. The scheduler includes a task list of scheduled 
server tasks to be performed. 
20 Fig. 13 illustrates a situation where a browser requests a document containing an 

EMWEB STRING tag whose processing is expected to interfere with other application 
operations. The initial HTTP request 1 301 for the document is acknowledged 1303, 
conventionally. When the EMWEB_STRING tag is encountered, control transfers 1 305a to the 
appropriate source code fhigment 1 305b in the application. The application then calls the 
25 suspend function 1307 of the EmWeb*^"/server and returns a dummy value 1309 to the function 
call generated at the EMWEB_STRING tag location. Calling the suspend function 1 307 causes 
the scheduler to remove the EMWEB_STRING processing task firom the task list. When the 
application has finally prepared the dynamic content required in the original function call, the 
application calls a resume fimction 1311 of the EmWeb™/server. Calling the resume fimction 
30 1311 requeues the EMWEB-STRING processing task on the task list, as the current task. The 
EmWeb'^"/server responds by calling 1 305c the function 1 305d defined at the 
EMWEB_STRING tag again, this time immediately receiving a response from the application in 
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which the requested dynamic content 1313 is returned. The dynamic content is then served to 
the browser 1315. 

The suspend/resume feature is particularly useful in distributed processing environments. 
If an embedded application is running on one processor of a distributed envirormient, but 
5 dynamic content can be requested which is obtained only from another processor or device in the 
distributed envirorunent, then the use of suspend/resume can avoid lockups or degraded 
processing due to the need to obtain the dynamic content through a communication path of the 
distributed cnvirormnent. Consider, for example, a distributed system including a control or 
management processor, and several commimication devices. An embedded application running 
10 on the management processor can be queried for configuration data of any of the communication 
devices. Without suspend/restmie, obtaining that data would tie up the communication path used 
by the management processor for control of the various communication devices, degrading 
performance. 

The described embodiment of the invention illustrates several advantages thereof For 

1 5 example, an embedded application can now have a GUI which is independent of either the 
application platform of that used to view the GUI. For example, the GUI can be operated 
through a Microsoft® Windows""^" CE machine, Windows^"** 3.x machine, Apple Macintosh, 
WebTV box, etc. nmning conventional browser software. Also, development of a GUI for an 
embedded application is greatly simplified. The look and feel is designed using conventional 

20 HTML design techniques, including straight-forward prototyping of the look and feel using a 
conventional client server system, using simple HTML extensions. Integration with the 
embedded application does not require the developer to learn or develop any special interface, 
but rather uses some HTML extensions to incorporate application source code directly into the 
HTML content. Yet another advantage in that the entire embedded application along with an 

25 HTTP-compatible server and the content to be served is reduced to a minimum of application 
source code, data structures for static data and data structures for dynamic data. 

The present invention has now been described m connection with specific embodiments 
thereof However, numerous modifications which are contemplated as falling within the scope 
of the present invention should now be apparent to those skilled in the art. For example, the 

30 invention is not limited to content whose source is HTML. Any mark up language could be used 
in the context of this invention. Alternatively, the content source could be raw text, which is 
particularly suitable for situations where the output of the user interface is also processed by one 
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or more automatic software text filters. Therefore, it is intended that the scope of the present 
invention be Hmited only by the properly construed scope of the claims appended hereto. 
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1. tntroduction 

The explosive growth of the Worid-Wi de-Web in recent years has created a new standard 
for the Graphical User interface (GUI) of networi^ed applications: the Web browser. 
Netscape®, Mosaic, and other commercial and public-domain Web browsers are 
ubiquitous and inexpensive. 



1.1, Web-based Network Management 

Network management is a natural application for the World-Wide-Web. Before the Web, 
network management required end-users to purchase expensive custom-built GUI 
applications that used the. SNMP protocol to manage network-based devices. With 
World-Wide-Web technology, many of these applications can be replaced by 
economical Web browsers. 

World-Wide-Web standards make It possible to migrate the "look-and-feel" intelligence 
of the device configuration GUI away from third-party and custom-built network 
management applications and into the managed device itself. This migration gives 
vendors control over the configuration "iook-and-feel" of their products among both low- 
cost Web browsers and the high-end third-party network management applications of 
the future. 

Web-based network management can greatly accelerate the time-to-market for 
products traditionally managed by SNMP. With SNfvlP-based management, new 
product features require significant engineering resources to design and implement 
proprietary MIBs and develop customized GUI applications to manage the new features. 
On the other hand, Web-based management GUI applications can be rapidly prototyped 
and Implememed using simple HTML forms. 

SNMP will continue to play an Important role in high-end network managemem 
applications by utilizing standard MIBs to monitor the overall topology and health of 
devices throughout the enterprise network. However, the new Worid-Wide-Web 
standards offer an exciting alternative to SNMP for the configuration and managemem 
of individual devices. 

1.2, Web-based Systems, Devices, and Software 

Embedded Web sender technology can enable remote configuration, monitoring and 
diagnostic capabilities for a wide range of applications. Imagine sending and receiving 
faxes, checking your voice-mail, and knowing the availability of your favorite candy bar 
In the vending machine down the hall by using your Web browser? Your office manager 
could configure the phone switch and voice-mail system, check the toner and paper 
levels in the photocopying machine, and monitor the security alarm system from their 
desktop. Your automobile mechanic could connect to your car's computer to perform 
engine diagnostics, and if -they were stumped, the manufacturer could examine the 
results from around the worid over the Internet. 
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1.3. Goafs 

EmWeb*^^ by Agranat Systems is a family of Embedded Wortd-Wide-Web protocol 
software products engineered for the demanding real-time requirements of embedded 
systems. 

Goals of the EmWeb product architecture include: 

- Ease of use 

. Support rapid prototyping and Implementation of new World Wide Web interfaces 
including device monitoring, configuration, and network management 

. Easily portable to a wide-variety of real-time embedded operating environments 
with limited operating system capabilities, memory, and CPU resources. 

. Easily upgradable with new releases as Wortd-Wide-Web standards continue to 
evolve rapidly. 

- High performance 

. Efficient implementation for real-time processing environments. 
. Small foot-print to minimize FLASH and RAM resources required. 

- Security 

. Support for authentication and security standards as they continue to evolve. 
. Configuration of method-independent access controls. 



1.4. Assumptions 

This functional specification assumes that the reader is familiar with the C programming 
language, the World-Wide-Web, and standards such as HTML (Hyper-Text Markup 
Language). Knovirtedge of HTTP (Hyper-Text Transport Protocol) and CGI (Common 
Gateway Interface) is also helpful to understand some of the more advanced features, 
but isn't required for most applications. 
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2. Overview 

One draw-back to traditional World-Wide-Web servers Is the CGI Interface. Although 
HTML provides a convenient mechanism for sending interactive fomis to a Web browser 
complete with text fields, checkboxes, and pud-down menus, the CGI Interface used by 
sen/er applications to process submitted fomis Is difficult to master. Form processing is 
essential for network management applications because it is the best way to implement a 
device configuration screen using World Wide Web protocols. However. CGI is not an 
appropnate interface for the rapid implementation and prototyping of new network 
!?/^^H!?lf (EmWeb's number one goal). Another draw-back to traditional 

World-Wide-Web servers Is the static nature of the content of files served to the Web 
browser. These files are typically resident on disk and are not expected to chanoe 
frequently. On the other hand, the data of interest to network managemem applications is 
constantly changing (e.g. the number of packets received on a particular Ethernet port). 

The EmWeb architecture works around the draw-backs of traditional World-Wide-Web 
servers by extending the standard HTML specification with new proprietary taps 
deve oped by Agranat Systems. These tags make it possible to provide a more Me 
HTfvIL form processing Interface for embedded systems, and give the application run-time 
control over the document content for the presentation of dynamic data Note that thesi 
tags are not actually sent to the Web browser. Instead; they ^rstripped oJ^ 
interpreted by the EmWeb/Compiler. ^inppea out ana 

EmwfSlse^rv^ ^"^'^^^ components: The EmWeb/Compiler and the 

Jo!i!"^®^/^°T"!'' ^ ^°°iP^vided by Agranat Systems that runs on an engineering 
developmem wori^-staton under Unix. Windows/NT (x86). and Windows/95 The tool 
compiles one or more directories of files containing HTML. Java, text, graphics, etc., into 
one or more EmWeb arrives. Each archive consists of an object code component ar!S a 
fixed data component. These components are usually linked imo the target's run-time 
image at compile time. However, the EmWeb architecture pemiits the dynamic loading 
and unloading of the fixed data components at run-time. Furthermore, if the taroefs 

S rii^'^^"" P^'^'.^f "^^^^^^ '•"^^^"S ^de modules, Ihen 

entire archives may be loaded and unloaded at run-time. ^^uic*, uien 

The EmWeb/Server is a portable ain-time library implemented in ANSI C which is 
compiled and linked with the target platfomi's application software. ThTEr^WeWS^er 
knplemems the HTTP protocols to handle requests from Web browsers and irrtl^^^^^^^^ 
with the arrives created by the EmWeb/Compiier. The EmWeb/Server implem 
application interface (API) to the target software environment's memon^Ta^S^ 
buffer management, and TCP/IP protocol stack. managemem, 
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3. EmWeb/CompUer 

The EmWeb/ComplIer processes directories of HTML and other Web documents to 
generate ANSI C code. The generated C code is then compiled using a C cross-compiler 
to generate object code lor the target system. HTIvlL forms are translated by the EmWeb/ 
Compiier into a simple C function call interface customized to the application. The 
software developer is responsible for implementing the application-specific C code using 
these simple interfaces. The EmWeb/Compiler can generate function prototype 
definitions (a C include header file) to ensure correctness, and optionally generates stub 
functions to accelerate development 

The figure below illustrates the operation of the EmWeb/Compiler, 
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3.1. Em Web Context 

The Em Web/Server maintains a handle of type Ewscontexc at run-time that corresponds 
to a specific HTTP request from a Web browser client. This handle is made available to 
the application code responsible for providing the run-time content of HTML documents 
and fomis. 

The EmWeb/Server contains a library of functions available to the application for 
extracting information attached to this handle. For example, the application may want to 
detemiine the type of browser making a request, and change the looI<-and-feel of the 
requested document to take advantage of features available to particular browsers, in 
this example, the application could extract the browser type as follows: 

bytes • evs Con textUser Agent (ewsConcext, 

U5er_agenc, sizeof (*uaer_agenc) ) ; 

For more Information about available context information functions, refer to 4.1.5, 
Request Context Access, page 46. 



3.2. HTML Extensions 

The content to be provided by the EmWeb server is prepared as you would content for 
any normal Web server. The developer constructs a directory tree (or trees) of 
documents, which may include HTML documents, Java, text, graphics, and sound 
samples. The EmWeb compiler is then run over the content directory tree to build an 
internal database that is compiled and linked with the EmWeb/Server and the system 
code. 

EmWeb defines proprietary HTML tags and attributes for access to system data and 
dynamic system control of the served documents. These tags are never served to 
browsers by the EmWeb/Server, and because (v/ith one exception) they have no body 
part (they do not use a start and end tag, but only a stand-alone tag with attributes), they 
are ignored by browsers that see them when browsing the content tree either locally or 
via a non-EmWeb server. This facilitates testing and prototyping of content. 

3.2.1. EfWWEB.STRING 

The <EMWEB_sTKiKG> tag Is used to provide applications with run-time control of an 
HTML document's content by encapsulating a fragment of C code in the document 
itself. This C code Is executed as the document is being served to a Web browser and 
returns a nult-temiinated character string that is inserted as-is into the document in 
place of the <emmeb_string> tag. 

To include content in a document (which may include any standard HTML): 

<EMWEB_STRING C-'...; return (char •) somestring; ' > 

or 

<EMWEB_STRING EMWEB_ITERATE C"'.,.; xetuin (char *) sonestxing; ' > 
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The EmWeb/Compiler extracts the C language code fragment from the emweb_string 
tags in an HTML document and constructs a C module from them. Each fragment must 
end with a tecum statement that returns a pointer to a null-terminated string (or a null 
value which inserts no content). When the location of the emweb^string tag in the 
content is reached, the EmWeb/Ser/er executes the code fragment and inserts the 
returned string Into the document. If the optional emweb_iterate attribute is specified, 
the code fragment is called repeatedly until it returns a null pointer value. The number 
of iterations already processed (beginning with zero) is available to the code fragment 
by calling: 

ewsContexcicexacions (evsConcext) ; 

Note that the local variable 

£ws Context evsConcexc; 

is made available to the emweb^string C code fragment by the EmWeb/Compiler. 

The returned string must not be an automatic (stack) variable. The value is copied for 
transmission by EmWeb/Server immediately after returning. Thus, a single static 
string buffer may be shared by multiple code fragments. If pre-emptive multi-threading 
is to be used, the application may maintain a per-request buffer as part of its network 
handle. Alternatively, emweb_iterate may be used to support dynamic allocation of the 
string buffer as follows. On the first Iteration (#0), memory may be allocated, filled with 
data, and returned to the Em Web/Server for transmission. On the second iteration 
(#1), memory may be released and a null pointer returned to tenninate the iteration. 

The EmWeb/Compiler treats the embedded code opaquely; from the compiler's point 
of view, the code is simply a string of text that gets assembled into a generated code 
file. (See 3.6. Compiler Output, page 25). 

As such, the EmWeb/Compiler needs to know the beginning and end of the embedded 
C code fragment. The character following the c» attribute in the emweb string tag 
identifies the "bounds" of the embedded C code. This character must"be either a 
single quote 0 or double quote {"). When the EmWeb/Compiier identifies this 
"boundary character, it then treats all following characters as part of the embedded C 
code fragment, until It finds the next temiinating "boundary character". 

The obvious problem here is that the embedded C code can contain a single or double 
quote as part of the C code. For example: 

return "Exanple of EoMeb'B dynamic conCent\n"; 

In order to keep the EmWeb compiler from mistakenly confusing a single or double 
quote that belongs to the C code fragment as the ending "boundary character^, the 
programmer must escape (using 'V) any character intended for the C code that would 
be confused with the terminating boundary character. Thus, the above code fragment 
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could be embedded in an emweb_strinc tag In either of the following ways: 

<EMWEB_STRING C"'return "Exainple of EmWeb\'s dynamic content\n"; ' > 
<EMWEB__STRIMG C""recurn Example of EmWeb's dynamic concenc\n\" ; "> 

The <EMWEB_sTRiNG> tag may optionally be typed using the emweb_type attribute as 
follows: 

<EMWEB_STRING EHWEB_T5fPE •DECIMAL UIMT C"' 

rattirn {uiiiC32 *> &some~inceg«r; ' > 

If E«wEB_TYPE Is Specified, then the C code fragment must return a pointer to data with 
the con'esponding type. EmWeb/Server will convert the value Into a character string 
automatically. A table of supported types can be found in section 3.2.5.3. HTML Fomi 
TEXT Input I=ie!ds, page 13 

3.2.2. ElVIWEBJNCLUDE 

The EmWeb/Server provides server-side inclusion of any part of its content tree using 
the EMWEB_iNCLUDE tag; It Is used In the same way as the emweb_string tag: 

<EMWEB_INCLUDE COMPONENT "'Local-URL'J 

or ~ 

<EMWEB_INCLUDE C"' . . , ; letuin (char •) localORL; • > 

or 

<EMWEB_INCLUDE EMWEB_ITERATE C»'...; return (chax *) localURL;'> 

If the COMPONENT tag is specified, the specified local element is resolved and inserted 
into the current document. This allows standard parts such as headers and footers to 
be stored only once. 

As in EMWEB_STRiNG, the fragment specified by the c- attribute must end with a return 
statement that returns a pointer to a null-temninated string (or null). For 
EMWEB_iHCLODE, however, this string is treated as a relative or absolute path name 
within the local content tree. The path name Is resolved to an entire document, which 
Is then inserted in the current document for return to the browser. If the optional 
EMWEB_iTERATE attribute Is Specified, the code fragment is called repeatedly until it 
returns a null pointer value. The number of iterations already processed (beginning 
with zero) is available to the code fragment using the same access routine used for 
emweb_strimg. This tag is useful for building a response from components that may 
be part of the 'original document tree, or created dynamically. 

Note that the local variable 

EwsContexC evsContext; 

Is made available to the emweb^include C code fragment by the Em Web/Compiler, 
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The same quoting rules as emweb_strihg apply to emweb^incltoe. 

3.2.3. EMWEB.HEAD 

Because the <EMWEB_STEaNG> and <emwbb_include> tags allow the application to 
encapsulate fragments of C code within an HTML document, a mechanism is needed 
to provide the code fragments with the necessary global definitions, header files, 
external declarations, etc. needed for compilation. The <emweb_heai» tag is prowded 
for this purpose. 

<EMWEB_HEAD C" ' ftinclude file-naroe.h' > 

The EMWEB_HEAD tag, If present, should appear in the head portion of the HTfvlL 
document (this is not enforced, but the code fragments from all emweb_head fragments 
are placed at the beginning of the generated module, so doing so Is less confusing);' it 
specifies a source fragment to be inserted In the generated module outside any C 
function. This fragment may dedare variables, constants, or (as shown in the example 
above) C preprocessor directives - it could even define entire subroutines. This 
fragment Is never executed directly by the Em Web Server, so it does not Insert any 
content into the document at the location of the tag. 

Note that all emweb__head code fragments from all HTML files in an archive are 
combined into the generated archive object code component source file. Therefore, it 
is recommended that common « include directives appear only in one document in the 
archive (typically, the index.html document at the archive's root directory). 

The same quoting rules as emweb_string apply to emweb_head. 

3.2.4. EfyiWEB_PROTO 

When designing an HTML document, It may occasionally be useful to provide content 
with which to preview the page, but which does not appear in the compiled document. 
This is accomplished with the emweb_proto begin and end tag; the EmWeb/Compiler 
removes these tags and everything between them when producing the document 
database, but the text between them Is interpreted nomnally by a browser viewing the 
HTML document directly or via a conventional server. For example: 

<H4> 

System: <EMWEB_STRING C-^recurn mibZsysName; "> 
<EMWEB~PR0T0> sy s tern • name </EMWEB_PR0T0> 

</H4> ~ 

When compiled, the system name displayed in the first level header will be the value 
in the string variable inib2sysNaine, but viewed with a browser when previewing It looks 
Uke: 

system: system-name 

Note that the EmWeb/Compller ignores HTML comments (e.g. "< : . - ... ..>"). If 
EMWEB STRING and EMWEB_iNCLUDE tags are present within HTML comments, they will 
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be expanded by EmWeb/Server. It it is desirable to "comment out" an emweb_string 
or EMWEB^iNCLUDE tag, EMMEB_pROTo tags should be used instead. 

3.2.5. Forms 

Form processing takes place as two operations: serving the form to the browser, 
possibly with current or default values set in some form input elements, and 
processing the values from the submitted fomi. Each of these operations is assisted 
by an application -provided routine associated with the form. Prototypes for these two 
application routines are produced for each form by the EmWeb/Compiler using 
information provided by EmWeb attributes on the FORM and its input elements. 

Restriction: While HTML allows it, EmWeb does not support 
nested rouM tags (you may not have a form within a form). 

The elements for each fomn are combined in a generated C data stnjcture by the 
EmWeb Compiler; this structure is passed by the EmWeb Server to each of the two 
fomi processing routines, and includes Information on the status of each element 

3.2.5,1. Form Element Names 

The EMWEB_NAME attribute is used to specify the names to be used by the EmWeb/ 
Compiler when generating function and structure names. 

On the FORM tag, the emweb^name attribute specifies a base name to be used to 
generate the function names and the form data stnjcture name. (This implies that the 
value of the emweb_name attribute must be a valid C identifier). Note that if emweb name 
is not present In a <form> tag, then the form is simply ignored by the EmWeb/ 
Compiler and is passed as-ls to the brov/ser. 

Consider the following example. Suppose there exists an HTML document 
■example.htm!" that contains: 

<F0RM METH0D"P0ST EMWEB_NAME»f oo ACTI0N"lJar > 

The ACTION attribute Is optional; If action is not specified, then there may be only one 
form in the document if action is specified, it Is served to the browser as 
"ACTioN-exampie. html /bar". (This allows EmWeb/Server to differentiate between 
multiple forms in a document It also allows the submission of forms to be protected 
by different access controls than the serving of forms. See 3.4. ACCESS Files, 
page 22). 

The EmWeb/Compiler generates the following function and structure prototypes: 

typedef struct EwaForin_foo_s 
{ 

struct 

i 

it* 

} value; 
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sczucc 
{ 

• « « 

] scatus; 
) EwaPoim_foo; ... 

void ewarorinServe_/oo (EwsContext concexc, EwaForin_foo •foxnip) ; 
char * evaForinSubinit_jfoo (EwsContext context, EwaFoxm_/oo «f oxmp) ; 

The ellipsis (,..) above are replaced by declarations of the structure members to hold 
the data for each form element The standard HTML name attribute is used in each 
INPUT tag of the fonm to specify the structure member names within the form data 
strticture. 

Restriction: While HTML allows arbitrary string values forwiME 
attributes^ EmWeb requires tftar nahb attributes are valid C 
identifiers since they are used as field names in the form's C 
structure definition. 

The application-provided ewaForBiserve_/oo function is invoked by EmWeb/Server 
when the HTML document containing the form Is requested by a Web browser. This 
provides the application with an opportunity to modify the default values displayed 
by the browser at run-time. 

The application-provided ewaFormsubtni t_/oo function is invoked by EmWeb/Server 
when the corresponding HTML form is submitted. This provides the application with 
an opportunity to process the submitted fonn data and generate an appropriate 
response. 

3.2.5.2. Form Data Structure 

The generated fonm data structure passes information for the forni between the 
system and the EmWeb/Server. It has two sections: Value' and 'status', each 
containing one or more members for each form element. The 'status' section 
member is a fiag that Indicates the status of the contents of the 'value' member. The 
Value' member contains the data for the fonm element in an internal representation 
which may be specified by the form author using the emweb type attribute. For 
example: 

<INPUT nfPE-TEXT SIZE-IS MAXSI2E-15 VALUE-127 . 0 . 0 . a 
HAME-i/AcfdJ EMWEB_TYPE"DOTT£D_IP> 

The example above produces the following stnjcture members; 

typedef struct EwaForm_foo_s 
( 

struct 
{ 

■ t • 

uiat32 ifAddr: 
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uincf 
uincf 

* * * 

) value; 

3CXUCC 



ifAddr_inaxlength; 



uinca 



ifAddxt 



) scatus; 
) EwaFoxm_foo; 



The value. ifAddr member contains the host-order 32-bit tP address. The 
ewaForinsetve_jfoo function sets this Structure member with the value to be displayed 
on the form and sets status.ifAddi to Ew_roRM_iNiTiALi2ED. (Note that If 
scatus . if Addr Is not Changed by the application, then the fonm is displayed with the 
value specified by the value tag, "127 .0.0.1'). When the V\/eb browser end-user has 
entered a valid IP address and submits the form, the Em Web/Server sets 
value, if Addr to the value provided by the browser and sets sea cus. if Addr to 

EW_FORM_RETURKED befOre inVOking evaFoxinSubtniC_foo. 

.The value. if Addi^size member is generated because the size attribute was 
specified and defaults to 1 5. This gives ewaFormseive_f 00 an opportunity to override 
the field size value before serving the fomfi. (This field Is not used by 

eva Forms ubmi t_f 00) . 

The value. if Addi_[naxiength member is generated because the maxsize attribute 
was specified and defaults to 15. This gives ewaFormserve_f 00 an opportunity to 
override the maximum field size value at run-time. (This field is not used by 

ewa Fo I mS ubm i t_f oo) , 

The status, if Addr member is used to indicate the status of the form element 
member and consists of a bit field defined as follows (from src/inciude/ews_de£ .h): 



/* set if field initialized */ 
/* set if field ewaAlloc'ed */ 



/• set if value returned */ 
/• set if value invalid •/ 
/• or i/o error */ 

For the ewaFoxmServe _* call (when the form is being sent to the browser), the 
structure is passed w\Xh the status for each element set to either zero, or 
Ew_F0RM_iNiTiALi2ED If 3 default value was specified by the HTML vaule tag. When 



* For ewaFortnSexve • 
•/ 

ltdefine EW_FORM_INITIALIZED 0x01 
#define EW*'f0RM DYNAMIC 0x02 



* For ewaFormSubmi t_* 
*/ 

#define EW_rORM_RETURNED 0x10 
#define EW~FORM_PARSE_ERR0R 0x20 
ttdefine EW^PORm'file ERROR 0X20 
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control is returned to the EmWeb/Server, the server checks each status and uses 
the new value for each field for which the ew_form_initiali2ed is set Initialized 
values override any value, checked, or selected values specified in the source 
HTML document The ew_formj3vnamic flag is only valid for type fields containing 
pointers to data fmcluding text, password, hidden, textarea, submit, and 
EKWEBjrypE^HEXSTRiNc) and indicates that the memory referenced by the pointer 
was allocated by ewaAiioc and must be freed by EmWeb/Server using evanee after 
the form Is served. 

When the form Is submitted by the browser, the server attempts lo convert each 
value returned by the browser to the appropriate type. The server sets the status 
memberto Indicate the status of the data member of the structure, and then calls the 
evaFoxmsubraic_* routJne assodated with the form. The Ew_FoRM_jiETuimED flag is s.et 
if a valid value was returned for the field in the submission. The 
Ew_FORM_PARSE_ERROR flag is Set If 3 valuB was returned, but was not parsed correctly 
for the specified EMWEB_TypE. 

Note: When a form is submitted, the contents of a value f/eicf is 
undefined uniess the ew_form^returned flag is set in the 
corresponding status byte. 

The application processes the submitted values and returns a string containing the 
URL to use as the redirection response to the Web browser, or null for an empty 
("204 No Content") response. Alternatively, the following function may be invoked to 
return a local relative URL from the archive as a response. 

Ewssucus evsConcexcisenclReply ( £ws convex c contexc, chax * uxl } ; 

3.2.5.3. HTML Form TEXT input Fields 

A text field can be used to represent a wide variety of value types. For example, a 
text field may be used to configure an IP address in which case the natural C- 
language representation is a host-order 32-bit integer. By default, a text field Is 
simply a null-terminated character string. However, the emweb^type attribute may be 
used to indicate any of a number of supported EmWeb types. Refer to the table 
beiow for details. 

HTI^L text fields may specify a field size and/or a maximum length, if so, additional 
_size and _inaxi«ngth Structure members are added to the form stnjcture to give the 
application run-time control over these values, the format and resulting fonm 
structure fields of a text input field is given betow. 

<INPUT type-text HAME-iiajne {MAXLEWGTH-ftinax) (SlZE-ftsize) {VALUE-valuel 
{EMWEB_TYPE-«irt7P«) > 

BwType name; /• defaults to value •/ 

uincf nams^tnaxlength; /* defaults to ftmax */ 
uintf name size; /* defaults to #size */ 
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The following table lists all i;mweb_tvpe values currently supported. 



EMWEB.TYPE 


C-Type 


Description 


(not specified) 


char * 


nun-terminated string 


DECIMAL_Iirr 


int32 


32-bit signed integer 


DECIMAL_UINT 


ulnt32 


32-bit unsigned integer 


tl£Jt_±«T 


uinC32 


32-b]t unsigned hex integer 


roTrED_ip 


uinc32 


32-bit host-order IP address translated using 
the conventional dotted-quad ASCII notation. 


IEEE_MftC 


chai [6] 


IEEE MAC address (any of ':' or or " is 
accepted between bvtefi an inmrt HtcniawAW 
With ':•). I/G bit is least significant (Ethernet) 


FDDI_MAC 


chax [6] 


FDDI MAC address (any of ':' or or " is 
accepted between bytes on input, displayed 
With -}. i/G bit IS most significant (FDDI, 
Toi^en Ring) 


STD__MAC 


chaz I6] 


A MAC address - if or " is used between 
bytes on Input, it is Interpreted as IEEE (I/G 
bit is least significant); if is used on input, it 
is interpreted as FDDI (I/G bit Is most sianffi- 
cant). Displayed as IEEE with 


HEX_STIIING 


strucc { 
uiiiC32 length; 
uinCQ *da,cap; 
); 


A hex string. Any of ':' or or " or white- 
space is accepted between bytes. Displayed 
with". 


DECNET_iy_ADDRi;SS 


uintie 


area.node 


OBJECT__ID 


struct { 
uint32 length; 
uint32 *datap; 
J; 


A variable length array of unsigned decimal 
integers displayed with periods between ele- 
ments. 



Note that support for additional EmWeb types may be added in future releases. 



3,2.5.4.,HTML Form PASSWORD Input Fields 

A password field is represented by a null-terminated character string, HTML 
password fields may specify a field size and/or a maximum length. If so, additionai 
_size and ^maxiength Structure members are added to the form structure to give the 
application run-time control over these values. The fomiat and resulting form 
structure fields of a password Input field Is given below. 
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'wSISBl^ri^err°^ NAME-ijaina {SIZE-SsizeJ {MAXLENGTH-ftmaxlength) 

char *flanie; /. defaults to value, or NUIX*/ 

uintf i3arae_size; /• defaults to ftsize •/ 

uintf name_inaxlength; /* defaults to ftmaxlength V 

3.2.5.5. HTML Form CHECKBOX Input Fields 

Checkbox fields are represented as booleans. The optional value field is passed 
unchanged to the browser and Is not used by Em Web. 

<1HPUT TYPE-CHECKBOX NAME-Jiame {VALUE-value} (CHECKED) > 
boolean name: h defaults to TRUE if CHECKED, else FALSE */ 

Hotel If the Etf_FoiiM_RSTuitNED bit in the status byte is set on 
submission, then the checkbox was checked and the value is 

TRUE. 

3.2.5.6. HTML Form RADIO Input Fields 

Radio buttons are represented by a C enumerated type generated by the EmWeb/ 
Compiler tor each unique vALt;E assigned to a radio button in the archive (The 
enumerated types defined by radio buttons and single select options are c^mbSed 
into a single archive-wide enumeration). comoineo 

<1NPUT TYPE-RADIO NAME-name VALUE-vaJuej {CHECKED} > 
<INPUT TYPE-RADIO KAME-Jiajne VALUE-vaiue2 (CHECKED) > 

typedef enum EwaFoxmEnum ew a i chive e 
{ - - _ 

, vaJuei 
, value2 

t « « 

) EwaFoiinEnuni_e»^ar chive ; 
EvaForBiEnum_ew_axchive najne;/* defaulcs to checked value •/ 

Restriction: While HTML aiiows arbitrary string values for value 
attnbutes, EmWeb requires that value attributes for radio 
buttons are valid C identifiers since they are used as 
enumerated type identifiers. 

Note that EmWeb/Compiier generates a single enumeration for each archive The 
S^ontragS."""' f^^^ 3.5 compiler 

The following function is provided as a convenience for translating from the 



Copyright Ql 997 Agranat Systems, inc. Page 15 

REV. 6/20^7 



SUBSTITUTE SHEET (RULE 26) 



PCT/US97/I3817 



EmWeb/Compiler 

enumerated type's integer value to its name as specified by the value attribute:. 

const chai •ewaForraEnumToSciing ( Ewsconcexc concext, int value } ; 
3.2.5.7. HTML Form IMAGE Input Fields 

Images are "read only" from the point of view of the application as they return the x 
and y Image coordinates selected by the end-user from the Web browser. Therefore, 
the generated structure value members are only useful in the ewaFormSubmit„* 
application function. Structure members are generated representing the x and~y 
coordinates as follows. 

<INPUT TYPE-IMAGE NAME-J3dune SRC-sxc (ALIGN-align) > 

t:ypede£ struct EwaFoim foo s 
{ 

struct 

{ 

k > • 

uint32 Jiame^x; 

uint32 name J/; 

* • ■ 

} value; 
struct 
{ 

uints namei 

} status; 
) EvaFozm foo; 



3.2.5.8. HTML Form HIDDEN Input Fields 

Hidden fields are identical to text fields except that they are not displayed (and thus 
not modified) by the browser. They are typically used by appiicalions to pass context 
infonmation to the browse. This context infomiation is returned to the application 
during submission. 

<INPUT TYPE-HIDDEN NAHE-jiame {VALUE-value} tEMWEB^TrPE-ewtypo] > 
BwType name; /* defaults to value if present •/ 

3.2.5.9. HTML Form SUBMIT Input Fields 

Submit buttons with name attributes are represented by a nuli-terminated character 
string. Submit buttons without name attributes are not included in the form structure. 

<INPUT TYPE-SUBMIT (NAME-name) {VALUE-vaiue} > 

chax *name; /* defaults to value if present */ 
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3.2.5.10. HTML Form RESET Input Fields 

No structure member is generated for a reset button, 

3.2.5.1 1 . HTML Form SELECT/OPTION Fields 

Select boxes may be used to select a single item from a list (the default), or multiple 
Items from a list (If the attribute multiple is present). For single Item sSon^^^^^ 
are represented by a C enumerated type generated by the EmWeb/ComDller rrhe 
enumerated types defined by i^dio buttons and single seled^Se^^^^^^ 
into a single archive-wide enumeration). cgmumea 

<SELECT iTAME-Jiame {SIZE-#si2e) > 

<OPTION VALUE-vaJuel (SELECTED) > 
<OPTION VALUE* vaJue2 {SELECTED) > 

</SELECT> 

typedef enum EvaFoimEnuoj ew at chive e 
. ( _ » _ 

, vaiuei 
, values 

) EwaPoxinEnum_ow_ajchive; 

EwaPoimEnuni_eh/_3jcAjve flame;/* defaults to selected value •/ 

For multiple item selection, a status and value form stmcture field Is generated for 
each option as follows: ^ ^taicu ^w 

<SELECT NAME-naflie {SIZE«|tsi2e] MULTIPLE > 

<OPTION VALtJE-vaJuea {SELECTED) > descripcive cexc 
</SELECT>'°''^°"'^'^""'"'"^^ SELECTED} > de^cTipzive text 



boolean vaiuei; 
boolean v&2ue2; 
uintf jjaiue^size; 



/• defaults to TRUE if SELECTED «/ 
/• defaults to true if SELECTED •/ 
/* defaults to ftsize •/ 



"^'"^^ °' selection box. If so, an additional 

fiestriction: While HTML allows arbitrary string values for value 
mributes, EmWeb requires that value attributes for select 
options are valid C IdenUfiers since they are used as 
enumerated type orstnicture field identifiers. 

3^.5.12. TEXTAREA 

The textarea value is a nuIMemilnated string of characters. Additional value fields 
are placed In the form structure forthe number of rows and columns in the text^e^^ 
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These fields are Initialized by EmWeb/Server to the defaults specified in the source 
HTML document, but may be overridden at run-time by the application's 

evaFoxmServe * function. 



<TEXTAREA .COLS«#cols ROWS-ftiows NAME»rtame > 
</TEXTAREA> 

Char *name! /• null- terminaced string */ 

uincf najne_cols; /• default to ffcols •/ 

uincf name_rows; /* default to #rovs •/ 

Note that the *name points to the text present in the textarea input field, 
3.2.5.13. File Upload 

RFC1867 file upload defines a new form input type as follows: 

<IJJPUT TYPE-FILE NAME-name tVALUE=value) £siZE-*frows { , ftcols) ) > 

Note: Use of file input types requires that the form uses 
multipart /form -data as an encapsulation type. This must be 
specified in the <form> tag as follows: 

<FORM METHOD-POST ENCTVPE -multi pait/f or m- data ... > 

This causes the browser to prompt the user for a local (relative to the browser) 
filename (by default, value is used if specified). On submission, the file is uploaded 
to the server along with other form field values. 

EmWeb/Compiler parses file type input fields into the following fields in the form 
value substructure: 

•najne; /• serve only; default filename •/ 

EwaFileHandle naflie_handle; /• submit only: received file •/ 

^^^^^ name^size; /• serve only; #row8 (no #cols) */ 

^intf name_rows; /• serve only: ffrows (w/«cols) •/ 

uintf naffle^cols; /* serve only: #cols •/ 

In addition, the following fields in the form status substructure are generated as well: 

"^^^^ name; /• status for filename •/ 

uiatB name_handle; /• status for received file */ 

For more detailed Information on the file upload interface, please refer to 4 1 8 Local 
Filesystem Interfaces, page 54. 

3.Z6. Graphic Maps 

The HTf^L isMAP attribute on an img tag specifies that the file is an image map. Such 
an IMG tag must always be enclosed within an anchor that specifies a hyper-link URL 
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The isMAP attribute ^uses a dick withfn the image to be sent as a request to the URL 
in the enclosing anchor, qualified by the x & y coordinates of the click within the image. 

EmWeb provides support for image maps through a map element in the HTML source 
tree which specifies rectangular regions and URLs to be associSed with them 

l}!trl^^^T^f^'^''^V^^^^^^ ^" ^^^Se map file, a text file which defines the URLs 
to be provided for each region of the image. The syntax of the entries is- 



lect-line | default-line 



xecc>Iine 



pome 



default -line 



lect uil point point 



: :• default uil 



The lect token specifies a.URL to be served in response to the specified top-left and 
bottom-nght coordinates. The optional default specifier provides URL for anS 
coordinate not specified by some xect (only one default !s ai owed). Srder of t^/r-t 
lines IS significant - If the regions overlap the first match takes precedence 

If no match is found, and no default is specified, the server retums "no content" to the 
bi^wser, effectively a no-operation. Otherwise, the matching URL is re?ume^^ to me 

SltSr ' ''''' ''''' "''^ '"'"'"^ ^° "^^P theTchive or 

The map files are compiled by EmWeb/ComplIer so that they do not need to be parsed 
atrun-time by the EmWeb/Server. The following illustrates L syntaJTof a 



file: 



rect examplei.html 15, IB 169,37 
rect examples. html 157,4 6 385,65 
rect examples. html 365, 7i 460,87 
default /home, html 

If the above file was "sample. map", and con-esponded to the imane . 
sa^^ie.gif". the following HTML would be used to imp^ment th^^ /p-^ures/ 

<A HREF-sainple.map"> <img SRC-Vpictuies/sample.gif - isMAP> </A> 

By convention, map files use the suffix W, but this can be chanoed ^ ^ 
m.me.types Configuration File, page 20. and 34. .ACCEsTpilLs. pa%^^*. 

3,2.7. Cache Control 

The HTTP/1.0 protocol has some simple provisions for communicatlna cachabiiitv 
information to caches and proxies between the server andTe bS ^TTPn T 
provides even greater cache control features. browser. mttp/i .1 
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By default, EmWeb/Server classifies compiled-ln documents as being either static or 
dynamic. A document is considered dynamic If it contains one or more emweb strings, 
EMWEB_iNCLUDES, or EmWeb-enhanced HTML fomis. Otherwise, the document is 
statia 

When serving a static document, EmWeb/Server sends a Last-Modified HTTP header 
indicating the time and date that the corresponding archive was created by the 
EmWeb/Compiier. No other cache control headers are generated in HTTP/1 .0. With 
HTTP/1.1, a Cache-Controi header Is generated Indicating either "public" If the 
document Is not protected by an authentication realm, or "private" if it is. 

When serving a dynamic document, EmWeb/Server sends a Last-Modified and 
Expires HT TP he ader indicating the cun-ent time and date, as well as "Pragma: no- 
cache" for HTTP/1 .0 and 'Cache-Control: no-cache" for HTTP/1 . 1 . 

It may be desirable to override the above default behavior for certain applications. 
Specifically, an application may desire static treatment of a dynamic document. For 
example, If emwed^include tags are used to insert common headers and footers. 
EmWeb/Seiver would treat the document as dynamic even though the content may 
actually be static. The following Em Web tag may be used anywhere in an HTML 
document to mark it as static for cache control purposes: 

<EMWEB__STATIC> 

3.2.8. EmWeb CGI 

The mechanisms described above are designed to meet most needs of the system 
designer without having to deal with the complexities of direct access to the HTTP 
input and output mechanisms. If such access is desired, the Em Web raw CGi interface 
provides access similar to that availabie in a CGI program environment on any HTTP 
sender. See 4.1.6. Raw CGI, page 51. 



3.3. mime.types Configuration File 

The mime . types configuration file is read by EmWeb/Compiier before processing source 
directories of HTML and other Web documents, if "-m" is specified on the Em Web/ 
Compiler command line, then the specified file is used Otherwise, Em Web/Compiler 
searches for a mime . types file by first looking at the semweb_mime environment variable, 
and then looking at $emweb_home/$emweb_mime. If the semweb_mime environment variable 
is not specified, it defaults to "mime, types". If the $emweb_home environment variable Is 

not specified, It defaults to Vusr/local/share/emweb". 

The mime.types file Contains default parameters for files derived from the file name 
suffix. For example: 



U EmWeb /compile I mime.types file example 

# Anything aftez a is a comment. 

# A line vhose first chazacter is vhite space is a continuation line 



Copyright 0 1997 AgranaX Systems, Inc. 



Page 20 



REV. 6/20/97 



SUBSTITUTE SHEET (RULE 26) 



wo M/06033 PCT/US97/13817 

-49- 

EmWeb'"'^ Functional Specification Confidsnbal . . EmWeb/Compiler 

U Each specifier anist end in ' ; ' 
# 

.html. tiype* text/html paise»cinweb_hcinl compiess ; 
,txt type-text/plain paiBe"Cinweb_text compiess ; 
,gif type- image/git paise-binary"; 
.nap inageinsp; 

index-index. html; 

The suffix may be any tali match; it is not restricted to values starting with The 
mime . cypes file contains specifiers for the defauH access rights and parameters of fiJes 
ending with a particular suffix. Each specifier is the file name suffix, followed by one or 
more of the following attributes, followed by a semicolon: 

type=m//73e-iype 

Specifies the MIME encapsulation media type represented by the file. Media 
type values are registered with the Internet Assigned Number Authority 
(I AN A). Use of non-registered media types is discouraged. (Note that the 
mime 'type must be quoted If it contains a ';' line-temninator character). The 
default type depends on the parser selected (see below). 

parse=emw^e£L/jf/73/ / emwebjtext / text / binary 

Specifies how the EmWebyCompiier is to parse the file. 



EMWEB_HTML Indicatcs that the file contains HTML and the EmWeb/Compiler 
handles <emweb_strinc> , <emweb_include> , <emweb proto> . 
<EMWEB_HEAD>, and EmWcb HTML forms. The default type" for the 
EMWEB_HTia parser is "cexc/htaii". 

EMWEB_TEXT Indicates that the file contains text which may contain 

<EMWEB_STR1«G> , <EMWEB_INCLUDE> , <EMWEB PR0T0> and <EMWEB HEAD> 

directives. However, such a file may not contain EmWeb HTML form's. The 
default type for the emwebjtext parser Is "cexc/piain". 

TEXT Indicates thafthe file contains text which should not be parsed (e.g. 
PostScript). The default type for the text parser is "cext/piain". 

BINARY indicates that the file contains raw binary data. The default type for 

the BINARYparserls "applicacion/occet-stream". 

The default parser Is binary if not otherwise specified, 
compress 

Specifies that the content should be compressed. The EmWeb 
compression algorithm creates an archive-wide dictionary of common 
strings which are referenced by the individual documents. Compression 
ratios for text files of 50% can be achieved if there is sufficient redundancy 
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throughout the archive. However, compression ratios will vary wideiy among 
applications. The default is no compression. 

nocompress 

Specifies that the content shouid not be compressed. (This Is typically used 
in an _access file to override a specification in mime . types). The default is 
- no compression. 

imagemap 

Specifies that the content is an imagemap that defines the coordinates for 
an image. This implies "hidden", and inherits realm membership from the 
current directory. 

ignore 

Specifies that the entry should be si<lpped (i.e. not included in the archive). 
This is typically used to exclude source control directories, backup files from 
editors, etc. 

The current directory is specified using '.' as the suffix name. Directories may contain 
the attribute: 

index«/ndex-//7e-name 

The element (in the directory) to be returned in response to an access 
request to that directory (a URL whose last component is the direaory 
name), 

3.4. .ACCESS Files 

Access to individual files and directories is controlled by a configuration file in each 
source archive directory named '_access'. The _access files contain specifiers for the 
access rights of elements in the coresponding directory (and optionally tor the directory 
itself using the '.' specifier). Specifiers in the .access file override specifiers in the 
mime. types file. Each specifier is the file name" (not a suffix) followed by any of the 
attributes defined above for mime, types. The. following additional attributes are 
permitted in ^access files. 

realm=rea//n-name 

requires that any request to access the file or directory must be 
authenticated in the named realm. If an empty realm is given (i.e. realm—"), 
then the file may be accessed without any authentication. See 4.1.4.' 
Authentication and Security, page 39. 

hidden 

Specifies that the file is included for use In constructirig dynamic content and 
may not be seen or accessed directly by a Web browser. (Note that the 
hidden and realm attributes are mutually exclusive). 
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link«w/7 

Specifies that this element Is linked to a different URL When accessing this 
file, the browser shall be redirected to the specified relative or absolute URL 
The link attribute may not appear wth any other attributes. 

If realm Is specified for a directory, ft applies as a default for ail files and subdirectories 
within the current directory. Spedflcatlons for individual files in an _access file override 
defaults specified for the directory. ^ 

If hidden Is Specified for a directory, it applies as a default for all Tiles and 
subdirectories within the current directory. Individual files and subdirectories may be 
overridden by specifying a zeaim. 

Note that a default '.' specification for index may be included in the mime . types tile and 
ovenidden In individual _access files. 

in addition to the elements in the directory, the _access file may specify the base name 
for CGI elements (which do not need actual files in the HTML tree). These are 
specified with the access attribute cgi below and may also have a realm attribute. 

cgi^symbol 

The element is a CGI application. The symboi value is used by the EmWeb/ 
Compiler to generate application-specific prototypes for the raw-CGl 
interface. See 4. 1.6. Raw CGI, page 51. 

Finally, form action URLs used when a browser submits an Em Web HTMLfomi to the 
EmWeb/Server may be protected by a specific realm which may be different from the 
realm of the document containing the form, in this way a form may be used to display 
data to a less restricted realm, while permitting changes only from users in a more 
restricted realm. For example, If the HTML file 'exampie.html" contained an EmWeb 
HTML form tag <roRM method-post EMWEB_NAME»foo ACTioN-bai>, the following 
specifier may appear In the _access file corresponding to the directory containing 

"example. hunl". . 

example, html/baz zealm>xeaiin-jiajDe 



Access control is only computed by the EmWeb/Server on the initial URL; if the 
element to be returned In response to the URL includes an emweb^include tag, the 
EmWeb/Sen^erdoes notperfomn an access check on those individual elements. 

3.5. Compiler Options 

The EmWeb/CompIier program "ewe" takes the following command-line arguments 
followed by a list of one or more directories and/or tiles with which to build an EmWeb 
archive. 
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( -n I -name ) <archiv©-symbol-base-name> 

The base symbol name produced by EmWeb/Compiler corresponding to 
the object part (and, If -c is.aiso specified, the data part) of the archive. By 
default, this parameter Is •ew__axciiive*. Thus, the following symbol is 
generated by the EmWeb/Compiier in ew code.c; 

EwsAichive ew_archive; 

And if the -c option Is specified, the foliovWng symbol is generated in 

ew__da ta . c. ■ 

uiacs ew_axcluve_datal] ; 

( -m i -mime ) <mime.types filename> 

The path name to the mime. types configuration file. By default, EmWeb/ 
Compiler looks in $emweb_mime (mijoe. types) followed by semweb^hqke/ 
$EMWEB_MIME (/»sz/J.ocsd/sh&xe/emve2>/inime . types). 

{ -u ] -uri ) <archive-url-base-palh> 

The base URL path of the generated archive. By default, this is 'f. 

{ -r I -raw ) ] ( -c 1 -c ) 

The output, format of the generated archive data component {raw by. 
default). If . -raw is specified, the data component of the archive Is written to 
the file ev_data.dac as a raw binary file. If --c is specified, the data 
component of the archive Is written to the file ew_data.c as a C file that, 
when , compiled, produces an array of data reference by the symbol 
ew__archive_ciata. Both flags may be spedfied on the command line to 
cause the generation of both raw and C output files. 

( -o i -output ) 

The prefbcfor generated files data.dat, daca.c, code.c, stubs. c, and 
pro CO . h (" . /evj by default), 

( -s j -stubs ) 

Generate ew_5cubs.c file containing stubbed-out versions of form and CGI 
functions normally provided by the application to facilitate rapid prototyping 
and development 

( -C I -no-compress ) 

Disable compression of the archive. (Ovenides compiess attribute in 

mime, types and J^CCESS files). 
(-11 -little) 

The byte-order of the generated archive data component By default, a big- 
endian archive Is generated. If .-little is specified, then a little-endian 
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archive is generated. 

( -P I -no-preprocessor ) 

Disable generation of #iine pre-processor directives in generated 
ew_code . c file; normally, these directives are included so that the C compiler 
and debuggers can find the original C in the source HTML documents. This 
option should only be used if your C compiler does not understand the 
'ifline' directive. 

( I -quiet ) I ( -v | -verbose ) I { -d | -debug ) 

The logging level. The -quiet options suppresses all but error messages. 
The - - verbose is spedfied, more logging output is produced. The • - debug 
is specified, still more logging output Is produced. The default (non of these 
options specified) Includes enors and some warning messages. 

( -V I -version ) 

Displays the EmWeb/Compiler's version. 



Two dashes In a row indicate the end of options. All remaining parameters 
are file and/or directory names. This is optional, as any parameter that does 
not begin with a '-' is assumed to be a file and/or directory name. 

3.6. Compiler Output 

The EmWeb/Compiler produces the following output files: 
8W_data.dat 

A raw binary file containing the data component of the archive. 
ew_data.c 

If the - - c option Is specified at the command line, this file is generated. It 
contains C code that, when compiled, defines an array of octets 
representing the data component of the archive and referenced by the 

global symbol uinte ew_archive_data I] . 
ew^code.c 

A C file that, when compiled, defines the object component of the archive 
referenced by the global symbol (EwsAichive) ew_aichive. 

ewj3roto.h 

This C header file is generated If the archive contains EmWeb HTML fomis 
or CGI documents.. The header file defines function prototypes and data 
structures for an application-specific Interface between Em Web/Server and 
application-provided functions responsible for serving and submitting forms 
and/or raw CGI processing. 
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ew^stubs.c 

lithe - -stubs option Is specified at the command line, this file is generated. 
It contains stubbed-out versions of form and CGI functions nomnally 
provided by the application to facilitate rapid prototyping and development 
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4. EmWeb/Server 

The EmWeb/Server is written in portable ANSI C and is easily integrated into a wide 
variety of embedded appiicatlon environments. EmWeb/Server impiements the HTTP 
protocol and responds to requests from networked Web browsers with documents stored 
In run-time archives created by the EmWeb/Compiler. 

The following figure Illustrates a typical EmWeb/Server device management application. 
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Figure 2: EmWeb/Server 
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4.1. Application Interfaces 

The EmWeb/Server application interfaces are divided into six functional areas including 
system interfaces, network interfaces, document and archive maintenance, 
authorization and security, request context access, and raw CGI. 

Many application interfaces are optional and can be configured out of the EmWeb/ 
Server at compile time. This offers the system Integrator flexibility in balancing the trade- 
offs between functionality, memory requirements, and system performance. 

Most application interfaces are provided by the EmWeb/Server and are called by the 
application. However, some application interfaces must be provided by the application 
and are called by the Em Web/Server. Function names beginning with "ews" and data 
types beginning with 'Ews" are defined by the sender for use by the application. Function 
names beginning with "ewa" and data types beginning with "Ewa" must be defined by 
the application for use by EmWeb/Server. 

Status codes returned by the EmWeb/Server to the application are of type EwsStatus 
and are defined as follows (from sic/inciudo/ews_def .h): 

/• 

• scatus codes recmned co the application by EmWeb/Server 
*/ 

cypedef enum £wsstatus_e 
I 

EWS_STATUS_OK, 
EWS~STATUS_BAD_MAGIC , 
EWS~STATUS_B AD_VERS I ON , 
EWS_STATUS_ALREADY_EXISTS , 
EWS_STATUS~NO_RESOURCES , 
EWS_STATaS_IN_USE , 
EWS_STATUS~NOT_RECISTERED , 
EWS_STATUS_NOT_CLONED , 
EWS_STATUS_NOT~FOUND , 
EWS_STATUS~AUTH_FAILED, 
EWS_STATUS_BAD_STAT£ , 

EWS~STATUS~BADJREA1^ * 
EWS_STATUS_FATAL_ERROR , 
EWS^STATUS^ABORTED 
) EwsStatus; 

Status codes returned by the application to the EmWeb/Server are of type EwaStatus 
and are defined as follows (from sic/inciude/evs_def .h) : 

/• 

* Status codes returned to EmWeb/Server by the application 
*/ 

typedef enum EwaSCatus^e 
I 

EWA_STATUS_OK, 
EWA_STATUS_OK_YIEU), 
EWA STATUS ERROR 
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) Evascacus; 

4.1.1. System interfaces 

The system functional interfaces are further divided into four functional areas including 
initialization, scheduling, memory management, and ttme-of-day services. 

4.1.1.1. Initialization and Shutdown 

Before any other application interface function may be used, the EmWeb/Server 
must be initialized. This Is accomplished by invoking the following function: 

EvsSCacus evsXnit { void ); 

This function returns ews_statos_ok on success. Otherwise, an enror code is 
returned. (ews_statos_no_resources is returned if EmWeb/Server was unable to 
allocate memory for inTernal hash tables, etc.). 

A graceful shutdown of the EmWeb/Server can be accomplished by Involdng the 
function below. This causes EmWeb/Server to terminate all outstanding HTTP 
requests and release all dynamically allocated resources. 

EwsScacus evsshutdovn { void ); 

This function returns ews_statos_ok on success. Othenwise, an error code is 
returned. (There are curreritly no conditions that cause an error to be returned). 

4.1.1.2, Scheduling 

The EmWeb/Server Is capable of serving multiple HTTP requests simultaneously. It 
may be configured at complle-tlme to use either Its own Internal real-time scheduler 
or to make use of an external scheduler provided by the application's operating 
system. 

If an external scheduler is to be used, HTTP requests may be multi-threaded if each 
TCP connection is handled by its own operating system thread. Otherwise, requests 
will be single-threaded. The evsRuno, ewssuspendo and ewsResumeO functions 
described below for EmWeb/Server's internal scheduler would not be used. Instead, 
all application <emweb_string> and <emweb_include> code fragments and 
evaFoimserve_« and evaFoiinsubinit_* functions are Invoked from the 

evsNeCHTTPReceiveO funCtlOh. 

If the interna! scheduler is to be used, HTTP requests are served from the following 
function: 

Evsscacus ewsRun ( void ] ; 

This function returns ews_status_ok on success. Otherwise, an em>r code is 
returned. (There are currently no conditions that cause an en*orto be returned). All 
application <emweb_string> and <emweb_include> code fragments and 
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ewaFormServe_« and evaForinsubmic_* functions are invoked from ewsRunO . 

The ewsRuno function processes any outstanding HTTP requests untii either all 
requests have been served, or the application requests that Em Web/Seiver yield the 
CPU as foNows. Each time EmWeb/Server sends a buffer of HTTP response data to 
the network via the application-provided ewaNetHrrPSend function, the appiication 
may return the status ewa_status_ok_yield to request that the Em Web/Server 
relinquish control of the CPU. This will cause the EmWeb/Server to return from the 
ewsRun ( ) function immediately, (Note that If the last buffer of the HTTP response was 
transmitted the EmWeb/Server will - close the connection and Xse 
conresponding resources before returning contrxil to the application). 

In addition, the internal scheduler gives the application a means to temporarily 
suspend a specific HTTP request each time it invokes application-spedfic code from 
<EMWEB_sTRiKG>, <EMWEB,iNcLUDE>, and HTML form serve and submit functions The 
app ication may instoict EmWeb/Server to suspend an HTTP request from the 
application-specific code provided In <ekweb_string> and <emweb ihclude> C code 
rragments. and Ewaroimserve,. and Ewarormsubmi c - functions by invokinq the 
following function before returning to the EmWeb/Server. 

EwsStatus ewsSuspend ( EwsContext context ) ; 

This function returns ews_status^ok on success. OthenA^ise. an error code is 
returned (ews.status_bad_state). When the appiication returns to EmWeb/Server 
after invoking evssuspend. the EmWeb/Server may continue to process other 
outstanding requests from evsRunQ before returning control to the application Note 

^nni? r^^'"' ^"'"9 ewssuspend is ignored T^ie 

applications <emweb_string> « <EMwzB_rNCLUDE> C code fragment or 
ewaFormseive » or ewaFoimsubmit_* function is re-invoked when the request is 
resumed. This functionality makes It possible to implement proxy servers (I e a local 
HTTP request might cause the application to send an IPG message o another 
process and suspend EmWeb/Server processing of this request until an IPC 
response is received). The application can resume a previously suspended request 
by invoking the following function. / k ucu .cnuesi 

Ewsstatus evsResiime ( EvsConcexc context, EvaStatus status ); 

Status can be either ewa_status,ok or ewa_status_ok yield. If the status is 
EWA_sTATus_oK, then the resumed request may be scheduled right awav (for 
example, this could cause ewsRun to be invoked internally). Otherwise the 
suspended request Is scheduled to run. but is not actually run untii control Is 
^ans eired back to EmWeb^eo^er. This gives the application control over w^^^ 
CPU thread processes HTTP requests (I.e. a-suspended request may be resumed 

^fn^J^^T''* ^""^ ^ P°"'"9 '^°P calls evsRun). TTliS 

unction returns ews^status_ok on success. Otherwise, an error code is re umed 
(ews_status_bad_state). 
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The lollowing function may be Invoked from within the application's <ekweb strino 

ot <EMWEB 1NCLTOE> C COde fragment or ewaFcrmSetve « or evaPormJubmi t * 

function to determine If this is the initial invocation of the ap"plication code or if the 
code IS being resumed. 

boolean ewsContextlsResuming ( EvsConcext contexc ) j 

This function returns true it the application code is being re-invoked after 
ewsResume. Othenwise. this function returns FALSE. "ivu^ea aner 

4.1,1.3. Memory Management 

Ir't^IX'^ir^"^^' 'l!^"^?^ application to provide simple memory management 
for the allocation ^d release of temporao^ data-structures used throughom me 
processing of HTTP requests and maintaining the mn-time document archie and 
authentication databases. These functions are equivalent to the S Ic Sd 

free Calls aS follows: 'naiioc Bfia 

void • ewaAlloc ( uincf bytes ) ; 
void ewaFxee t void • pointer J ; 

The ewaAlloc function (or macro) returns a pointer 1o available memor/ of at least 
the spea led number of bytes long.'or null if no memory is availab^The eJarree 
function (or macro) returns a biock of available memo'ry previously Med b^ 

ewaAlloc. ' 



Note: If the EmWeb/Server is unable to allocate memory 
dunng the processing of a particular HTTP request the 
request is aborted, all resources related to the request are 
released, and the application's ewaNetHrrpEnd o function is 
invoked. Alternatively, the application may implemem 
ewaAlloc {) SO as to block until resources are available usina 
external operating system facilities. 

4.1.1.4. Time-of-Day Management 

Some of the optional HTTP/1.0 functionality requires a -^ime^f-day" for Dace- 

const char * ewaDate ( void ) ; 

f^o'Jl^a^s?^"" ^^"""^ '^'""^ ^"^^ ^^^^ °^ ^he following two 

RFC11 23: (Preferred) 

Fri, 08 Jun a996 06:57:28 GMT 
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RFC850: 

Friday, oa-Jun-96 08i57!28 GMT 
4.1.2. Network interfaces 

The EmWeb/Server relies upon a pre-existing TCP/IP protocol stack available In the 
target software environment The interface between the application's TCP/IP protocol 
stack and the EmWeb/Server is event driven. This approach makes it possible to port 
EmWeb/Server to a wide variety of software environments. 

4.1.2.1. Network Buffer Management 

The EmWeb/Server design assumes that the application maintains data buffers for 
the reception and transmission of TCP data. 

Buffers can be uniquely Identified by an application-defined buffer descriptor. No 
assumptions are made about the actual structure of the buffer descriptors or their 
relationship to the data. For example, a buffer descriptor could be an index into a 
table, a pointer to a structure (either contiguous or separate from the data 
represented), etc. The application is responsible for defining the appropriate type for 
EwaNetBuf f er and a value for ewa_net_buffer_nuh,. 

Buffers can be chained together. Given a buffer descriptor, EmWeb/Server must be 
able to get or set the "next buffer in the chain" field. This is done by the 

evaNetBufferNextSet and ewaNetBuff erNextGet fUnctiOHS (or maCTOS). Note that 

the buffer chain is terminated when the next buffer value is ewa_net_buffer_null. 

EwaNecBuffer ewoNecBuf f eiNextCec { EwaNeCBuffer buffer ); 

void ewaNetBuf f erNexcSet ( EwaNeCBuffer buffer, EwaNetBuffer nexc ); 

Given a buffer descriptor, EmWeb/Server can determine the start of data in the 
buffer. Additionally, EmWeb/Server may change the start of data in the buffer 
(EmWeb/Server only moves the pointer to the data upward (Increments)). This is 
done by the evaNecBuffeiDatacec and ewaNecBuffeiDacasec functions (or macros), 

ulncB * evaNeCBuCfeiDaCaGet ( EwaNetBuffer buffer ) ; 

void ewaNeCBuffezDacaSec ( EwaNeCBuffer buffer, uinc8 *dat:ap }; 

Given a buffer descriptor, EmWeb/Server can determine the size of contiguous data 
in the buffer. Additionally, EmWeb/Server may change the size of the buffer 
(EmWeb/Server only changes the size of the buffer downward (decrements)). This 

is done by the ewaNecBuffeiLengChCeC and ewaNBCBuf ferLengchSec functions (or 

macros). 

uintf ewaNecBufferLengchGec { EwaNeCBuffer buffer) ; 

void ewaNocBuf ferLengchSec C EwaNecBuffer buffer, uincf length ); 
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EmWeb/Server may allocate a single buffer by invoking the ewaNetBuf feiAiioc 
function (or macro). The application may return a buffer of any size to EmWeb/ 
Server. The size of the buffer must be initialized to the number of bytes available in 
the buffer for EmWeb/Server, If no buffers are available, this function returns 
EWA_MZT_BurFER__HULL. Additionally, EmWeb/Server may release a chain of one' or 
more buffers by invoking the ewaNetBuf ferPiee function (or macro). 

EwaNetBuf fer ewaNetBuffer Alloc ( void ) ; 
void ewaNetBuffeiFxee {EwaNetBuf fei buf fei) ; 

Note: If the EmWeb/Seiver Is unable to allocate a network 
buffer during the processing of a particular HTTP request, the 
request is aborted, aJI resources related to the request are 
released, and the application's ewaNetHTTPEndo function is 
Invoked. AJtematively, the application may implement 
ewaNetiBuffeiAiiocC) SO as to biocK Until resources are 
available using external operating system facilities. 



4.1.2.2. TCP/IP Interfaces 

The application is responsible for listening to the HTTP TCP port (80) for connection 
requests. When an HTTP TCP connection request is received, the application 
accepts the TCP connection on behalf of EmWeb/Server and invokes the following 
function; 

Ews Con text ewsNetHTTPSCart { EwaNetHandle handle ) ; 

This function returns a new context handle which the application is expected to use 
when referencing this HTTP request for future operations. The value 
Ews_coNTEXT_NULL Is retumed on failure (e.g. no resources available to handle the 
, new request). The handle parameter is application-defined and is retumed to the 
application unchanged by the EmWeb/Ser/er in other network interface caiis as 
illustrated below. The handle is also made available to <emweb string > and 
<EMWEB_iHCLUDE> C code fragments and evaFoimserve * and ewrpoxmsubmit • 
application functions by invoking the following function: 

EwaNetHandle evsContextNetHandle { EwsContext context ); 

At anytime, the application can abort an uncompleted HTTP request by Invoking the 
following function: 

EwsStatus ewsNetKTTPAbort ( EwsContext context ); 

This f uncUon is typically Invoked by the application to notify EmWeb/Server that the 
corresponding TCP/IP connection has been disconnected. The function returns 
Ews_sTATus_oK on succsss. Otherwise, an eror code -'is retumed. (There are 
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cunrenliy no conditions that cause an error to be returned). 

As data buffer(s) are received from the network on a TCP connection corresponding 
to an HTTP request, the appiicalion passes these buffers to the EmWeb/Server by 
invoking the following function. 

EwsStatus ewsHeCHTTPReceive (Ews Con text concext, EwaNeCBuf fex buffer) ; 

This function returns ews_status_ok on success. Otherwise, an error code is 
returned, (There are currently no conditions that cause an error to be returned). The 
buffer parameter describes a chain of one or more buffers containing raw TCP data. 
The structure of the buffers is determined by the application, and the application 
provides EmWeb/Server with functions to manipulate these buffers as defined 
previously. Note that EmWeb/Sen/er takes responsibility for releasing received 
buffers when they are no longer needed, and may hoid on to buffers containing 
certain HTTP request headers for the duration of the request. 

When EmWeb/Server has assembled one or more buffers for transmission, it 
invokes the following function (or macro) which must be provided by the application: 

EwaStatus ewaHetHTTPSend { EwaNecHandle handle, EwaNetBuffer buffer ); 

This function transmits (and then releases) a chain of one or more network buffers 
and returns ewa_status_ok or ewa_status_ok_yield on success, or 
EWA_sTATus_ERROR on failure. If the application returns ewa_status_ok, EmWeb/ 
Seiver will continue processing outstanding requests In a round-robin fashion, if the 
application returns ewa_status_error, EmWeb/Server will abort the current request 
(as If ewsMetHTTPAboito was Called) and continue processing any other outstanding 
requests. The application returns EWA_sTA'nJs_oK_YiEU) to request that EmWeb/ 
Server give up the CPU. in most cases, evaNetHrrpsend o is called for each buffer's 
worth of HTTP response data generated by the EmWeb/Server. Thus, the CPU used 
by the server can be throttled by adjusting the buffer size available to the server and 
using the ewa_status_ok_yield return code. (See 4.1.1.2. Scheduling, page 29). 
Note that use of this return code requires that the application eventually either 
reschedule processing of the request by invoking ewsRun, or abort the request by 
Invoking evsNecHrrpAborc. 

The application may signal the EmWeb/Server with flow control events to indicate 
congestion on an outbound TCP connection, if a TCP connection's transmit window 
is full, the application may call the following function at any time: 

EwsSCatus ewsNeCFlowConcrol ( Ewsconcexc context ) ; 

This Will cause the EmWeb/Server to temporarily suspend processing of the request. 
When the TCP connection's window opens again, the application may Invoke the 
following function at anytime to notify EmWeb/Server that processing of the request 
may continue: 
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EwsStatus ewsNetUnrlovContiol ( Ews Context context) ; 

If ewsMetFiowcontioio is called from the ewaNetHTTPsendo function, then the 
application is responsible for transmitting the current buffer. However, 
evaNetHTTPsendo will not be called again until the application has called 
evsNetunFiovconcioK). Note that If evsNecFiovcontroi {) is invoked from oiitside 
ewaNetHTTPsendo , then EmWeb/Server may call evaNetHTTPsendo once before 
suspending the request In any case, the application should be prepared to receive 
notification of request completion as described below. 

When the EmWeb/Server has completed processing an HTTP request, or if the 
application aborts an outstanding HTTP request by invoking ewsNetHTTPAboico , rt 
invokes the following function which must be provided by the application: 

EwaSCatus ewaUeCHTTPEnd ( EwaNetHandle handle ) ; 

This function should dose the TCP connection corresponding to the request and 
return ewa_statos_ok or EWA_sTATtJs_oK_YiELD on success or eka_statos error on 
failure. Note that returning EWA__sTATus_oK_yiELD causes EmWeb/Server To give up 
the CPU. Otherwise, EmWeb/Server may continue processing other HTTP requests 
in progress. 

If persistent connections are used, it is possible that several HTTP requests will be 
handled over a single TCP/IP connection. For some applications, it is necessary to 
reset application-specific state infomiation and to release application-specific 
dynamic resources after each HTTP request. The following function may be 
provided by the application for this purpose: 

void ewaMetKTTPCleanup ( EwaNetHandle handle ) ; 

This function must be provided by the application or defined as a empty macro. It is 
invoked by EmWeb/Server when a request completes, allowing the application to 
reset any processing state stored in the networl^ handle. Note that for persistent 
connections, this routine may be called several times for the same connection, as 
one connection can be used for multiple requests. This routine will be called before 

evaNetHTTPEndO iS invoked. 

The EmWeb/Server must have access to an application-provided null-terminated 
character string representing the HTTP network location (e.g. 
"www.agranat.comrSO". Note that the host name (left of the V) may be a dotted 
decimal IP address. Aiso note that the ':<port-number>' may be omitted if the 
standard HTTP TCP port #80 is used. This string is returned by the following 
application-provided function (or macro). 

const chat • ewoNetLocalHostHame ( EwsContext context ); 



Copyright © 1997 Agranat Systems, Inc. Page 35 

SUBSTITUTE SHEET (RULE 26) 



REV. 6/20/97 



wo 98/06033 PCT/US97/13817 

-64- 

Til 

EmWeb Functional Specification Confidentiaf EmWeb/Server 

4.1.3. Document and Archive Management 

The EmWeb/Compiler generates an archive of one or more documents. Documents 
can be HTML files, JAVA programs, graphical images, or any other information 
resource addressable by a URL Archives may be independently loaded or unloaded 
Into the EmWeb/Server, 

In most applications, the entire set of available documents are compiled into a single 
archive and loaded at boot time. However, some applications may desire to 
dynamically load archives at run-time as needed in order to reduce memory 
requirements. In fact, applications may implement a scheme similar to virtual memory 
page swapping under some operating systems to cache an active set of documents in 
memory while storing other documents in a secondary storage area. Such a 
secondary storage area could be in FLASH memory, disk, or on a remote server using 
TFTP or other protocols to load documents at mn-time. 

An EmWeb archive consists of two components. First, there is the archive data 
component containing the database of compressed documents, infomiation about 
how to constnjct dynamic documents at njn-time, access controls, etc. Second, there 
Is the archive object component containing the run-time object code used for the 
construction of dynamic documents, etc. 

Operating systems supporting the run-time loading and linking of object code may off- 
load both the data and object archive components to a secondary storage Eire a. 
Otherwise, only the data components are off-loaded while the object components are 
statically linked into the run-time executable image. 

Each archive contains an archive descriptor in the object component. The archive 
descriptor is referenced by a public symbol generated by the EmWeb/Compiler. 

4.1.3.1. Installing and Removing Archives 

In order to activate an archive at run-time, the application must invoke 
evsDocumencinscaiiAz chive With parameters indicating the address of the data 
component and the archive descriptor of the object component. 

EwsScacus ewsDocumenclnscallAichive 

{ EwsAxchivo descriptoi, const uincB 'datap ); 

This function may return one of the following status codes: 

EWS_STATUS_OK The atchive was installed successfully 

EWS_STATUS_BAD_MAGIC The data or object portion of the ai chive is 

invalid or corrupt. This may happen if the 
EmWab/Seivei is configured for a big-endian 
archive when the EmWeb/Compiler generated a 
little -endian archive, or vice versa. 

EWS_STATUS_BAD_VERSION The archive generated by the EmWeb/Compiler 

is not understood by the EmWeb/Server . 

EWS STATUS ALREADY EXISTS The archive has already been installed. 
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EWS STATUS IN USE 



EWS_STATUS_NO_RESOURCES 



The archive contains a document vith a URL 
that has been previously loaded from a 
different archive. 

Insufficient dynamic memory is available to 
install the archive. 



The archive may be deactivated by invoking ewsDocumentRemoveAichive. 



EwsStacus evsDocumentRemove Archive < EwsArchive descriptor ); 

These functions return ews^statds^ok on success. Otherwise, ew status in use is 
returned Indicating that the archive contains documents that "are either~being 
processed by outstanding HTTP requests or that have been cloned to other URi_s. 

The fixed data component of an archive contains the name of the archive and the 
date it was created by the EmWeb/Compiler. These values may be retrieved as 
follows: 



const char • ewsDocumentAichiveName ( const uintB -datap ); 
const char • ewsDocumentAichiveDate ( const uints *datap 
const char • evsDocuiiientAichiveDatel036 ( const uints -datap }; 

4.1.3.2. Demand Loading 

in order to implement on-demand archive loading, the application may register 
document URi^ with the Em Web/Server which are valid but not loaded. This is done 
by Invoking the following function: 

EvsDocument 

BvsDocumentRegister (const chai *uj1, EvaDocumentHandle handle); 



This function returns an EmWeb/Server document descriptor of type EwsDocumenc. 
or Ews_DocuMENT__Nuu. OR cn-Qr. The handle is an application-defined value passed 
back unchanged to the application In ewaDocumentpauit as shown below. 

If a registered document is requested by a Web browser, then EmWeb/Server 
notifies the application by invoking the following application-provided funcUon: 

Ewascatus 

ewaDocumentFault ( EwsContext context, EvaDocumentHandle handle J; 

At this point, the application may load a new archive (possibly removing a previously 
installed archive to make room). When the archive containing the page is installed 
the EmWeb/Server automatically completes processing the request when the 
archive is loaded. The request can be aborted either immediately by returning 
EWA_sTATus_ERROR from ths evauocumentpauit functton. or by Invoking 

ewsNecHTTPAbort. 

Once a document is registered, there is no need to re-register it in the event that the 
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corresponding archive is removed. EmWeb/Server remembers that the document 
has been registered as dynamically loadable. However, the application may de- 
register a document by invoicng the following function: 

Ewsstatus evsDocumentDeregister t EwsDocumenc document ) ; 

This function returns ews_status_ok on success. Otherwise, ews^status in_use is 
returned indicating that the document was cloned or not registered. ~ 

4.1.3.3. Cloning 

Documents may be cloned and assigned to a new URL This allows multiple 
instances of a document to exist while minimizing the storage requirements. An 
application-specific handle can be used to identify an Instance of a document from 
the request context. 

The application clones a document by invoking the following function: 

EwsDocumencevfiDocuEnencclone 
{ consc char *ba3eurl, const char •newuil, EwaDocumencHandle handie ); 

This function returns a document descriptor for the clone, or ews_docukeot null on 
en-or. 

The cloned document may be removed by invoking the following function: 

Ewsstatus ewsDocumentRemove { EwsDocumenc document ) ; 

This function returns one of the following status codes: 

EWS_STATUS_0K The document was successfully lemoved 

EWS_^STATUS_N0T_CL0NED The documep.c is not a clone, 

EWS_STATUS_INJJSE The document is itself cloned. The clone of 

the clone must be removed first. 

All clones created from documents in an archive must be removed before the archive 
can be removed. 

Note that the application's document handle is made available to the application in 
the HTTP request context by invoking the following function: 

EvaDocumentHandle ewsConcextDocumentHandle ( EwsContext context ) i 

if the document corresponding to the context was not cloned or registered by the 
application, then this function returns ewa_document_handle null. 

4.1.3.4. URL Rewriting 

In some applications, it may be desirable to translate between URLs advertised to 
the outside world and URLs configured in the archive. The optional URL hook feature 
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provides the application with an opportunity to rewrite a requested URL before 
EmWeb/Server looks up the URL in its archive database. The following function (or 
macro) may.be provided by the application lor this purpose: 

chai * ewaURLHook { EwsConcext contexc. chat * uil ] ; 

This function passes the requested URL and request context to the application. The 
application may simply return uri if no rewriting is desired, or it may return an 
absolute local URL to substitute. The returned URL is looked up in the archive and 
served as if requested directly, if the application returns null, the request is aborted. 

This functionality is intended to allow the application to select a subdirectory of 
documents based upon requested language, content encodings, and other 
information available from the request context. 

Note that this function may rewrite and return any portion of the urI string parameter 
(provided that the string's length is not increased), or return a completely different 
string buffer instead. If a different buffer is used, the server copies the value 
immediately, 

4,1.3.5. Document Data Access • 

in some applications, it may be desirable to access the content of a file pointed to by 
a URL directly (e.g. data files used by CGI scripts, etc.). The following function is 
optionally provided by the EmWeb/Server to the application for this purpose: 

Ewsscacus ewsDocuotentOaca 

( const chaz * uzl, uinc32 'bycesp, const uincs **dacapp }; 

This function looks up the requested URL and, if found, updates *bycesp and 
^datapp with the length and pointer to the start of raw data in the file. (Note that the 
data is compressed if compression is enabled). Since EmWeb employs a proprietary 
compression technique, the application should specifically disable compression of 
files it wishes to access this way by using the nocompress attribute in the appropriate 
_AccEss file (see 3.4. .ACCESS RIes, page 22). This function returns ews_status_ok 
on success, or ews_status_not_fouhd on failure. 

4.1.4. Authentication and Security 

HTTP Authorization techniques are discussed in the HTTP specifications (see 7. 
References, page 87). Knowledge of these principles Is essential for correct use of 
these authorization interfaces. 

One or more HTML documents can be associated with a single "realm". A realm is a 
case-sensitive ASCII string that defines a "protection space" for the associated 
document(s). 

Each realm may have zero or more authentication entries associated with it. If a realm 
has no authentication entries, then documents in that realm are not accessible. 
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A dient that attempts to access a document associated with a non-nult realm is 
required to authenticate itseif. To authenticate, the client must send authentication 
parameters vaJid for at least one authentication entry for that document's realm. 
Clients that do not authenticate are denied access to the requested document. 

For example, assume a realm exists called "foo". It has three authentication entries 
associated with It (two using the "basic coolde" scheme defined in the HTTP/1 .0 
specification, and one using the "digest" scheme defined in the HTTP/1.1 
specification): 

REALM: "foo" 

Auchencicacion Enciy l: 
Type: "basic 

parameters : Usorname-"usezl" 
Password" "gucsc" 
EwaAuchHandle: <applicacion>s encryl identif ier > 

Authentication Entry 2: 
Type; "digest" ' 
parameters : Useznaine"*'user2" 

Password-"837I8U9 " 
'DigestRequired-FALSE 
EwaAuthHandle i <appIication' s entry2 identifier > 

Authentication Entry 3: 
Type: "basic" , 

parameters: Username" "Sinclair" 

Password* "baby Ion" 
EwaAuthHandle: <application*6 en try 3 identifier > 

When a client attempts to access a document assodated with realm "foo", it needs to 
authenticate against one of the above entries. Which one the client authenticates 
against is at its discretion. 

When a dient does authenticate against one of the above entries, the EwaAuthHandle 
for that entry is stored in the current context for the HTTP request (Ewscontext). The 
datatype of this EwaAuthHandle Is implementation-defined. 

The following types are defined for the authorization application interface (from src/ 

include/ ews_auth . h) 
/• 

* Defines the authorization schemes supported by the EmWeb server, 

* New schemes will be added as they aze supported. 

*/ 

typedef enum 
[ 

e w s Au ths chemeBa sic, 

ewsAuthSchemeDigest. 

e w 8 Au t hs chemeManua IBa sic, 

e w 5 Au t hs chemeHanua IDi g e s t , 
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ewsAuthMaxScheme /• count of supported schemes */ 

) EvsAuthScheme; 

/* 

* this structure defines parameters for all the supported 

* authorization, types. Hew parameters vill be added in 

* to this structure in the future 
*/ 

typedef union 
C 

#ifdef EW_C0NF1G_0PTI0N_A0TH__BASIC 

St^XUCt 

{ 

char *u8erKame; 
char *passWord; 
} basic; 

tfendif /* EW_CONFIG_OPTIOM_AXn'H_BASIC */ 
#ifdef EW_C0iiriG_0PTI0II_ATn'H_DIGEST 

Struct 

t 

char '*usexHatne; 
chax 'password; 

Hi ifdef EW_CONFIG_OPTioN_AUTH_DIGEST_M 

boolean digestRequired; /* require message daca verification */ 
# endif /* EW_COMFIG_OPTION_AUTH_DIGEST_M •/ 

) digest; 

# endif /* ew_config_option_autk__digest •/ 

char reservedl; 
) EwsAuthParameters; 

/• 

* This structure represents a single authorization entry. 
•/ 

typedef struct 

{ 

EvsAuthScheme scheme ; 
EvsAuthPaiameters params; 

GwaAuthUandle handle; /* user defined */ 
) EwsAuthoxization; 

An authorization entry may be created by invoking the foilowing function: 

EwsAuthBandle evsAuthRegister 

( const char *realm, const EwsAuthorization *authorization ) ; 

/ ■ 

This function returns an EmWeb/Server authorization handie which corresponds to the 
authorization entry, or ews_auth_kandle_null on failure. The entry contains the triplet 
(authorization scheme (e.g. basic cooJdel, scheme-specific parameters (e.g. user and 
password), application-specific authorization handle). 

The application-specific authorization handle corresponding to the authentication 
validating a particular HTTP request Is available from the context as follows: 
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EwaAuthHandl6 ewsConcexcAuctiHandle ( EwsConcext concext ) ; 

The application may remove a previously registered authorization handle by Invoking 
the following function: 

EwsStatus ewsAuthRemove ( EwsAuthHandle authorization ) ; 

This function returns ews_status_ok on success. Otherwise, an error code is returned 
(there are presently no conditions that result in en-or). 

By default, documents assigned to a non-null realm are protected and may only be 
accessed by authorized users, it may be desirable to enable or disable a realm's 
access controls. The following function disables access control for a realm making 
documents assigned to the realm accessible to everyone. 

EwsStacus ewsAuthRealmDi sable ( const char ♦ realm ); 

This function returns ews_status_ok on success, or ews_status_bad_realm if the realm 
was not defined by any loaded archives. 

The following function enables access control for a realm making documents assigned 
to the realm protected. Protected documents may only be accessed by authorized 
users. 

EwsStatus evsAuthRealmEnable ( const char * realm ] ; 

This function returns ews_status_ok on success, or ews_status__bad_realm If the realm 
was not defined by any loaded archives. 

The following function (or macro) must be provided by the application. The function is 
Invoked by EmWeb/Server to get a realm qualifier string from the application. The 
qualifier string Is concatenated with the base realm name in authentication protocol 
messages such that browsers may differentiate between realms of the same name 
appearing in multiple servers. 

const char ^ewaAuthRealmQualifiex ( void } ; 

The application would typically return the string "©hostname", where hostname is the 
server's local host name or IP address. The application may return null if no qualifier 
Is desired. 

4.1.4.1. Basic Authentication 

The Basic authentication scheme requires the browser client to transmit a Base64 
encoded usemame and password to the server for authentication. While no less 
secure than SNMP v1 , Basic authentication Is vulnerable to network monitoring and 
replay attacks. 

The authentication parameters for Basic authentication are simply the usemame and 
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password represented as null-terminated character strings. 
4.1.4.2. Manual Basic Authentication 

For some applications, It may be impossible to obtain the Basic authentication 
usemame/password pair prior to receiving requests for a document, instead, the 
Basic authentication username/password may be stored In a remote secure 
database. This database would need to be queried for the usemame/password as 
each request requiring authentication is processed. 

In order to support this, a special type of authentication scheme is defined: 
ewsAuthSchemeManualBasic This scheme is available only if the build option 
Ew_coNFiG_opTioN_AUTH_MBAsic is defined. Once defined, the application must 
provide the following Interface: 

boolean ewaAuthCheckBasic (EwsContexc context 

, const char *realn) 
t const chai *basicCookie 
, const chai *useiNanie 
, const chaz *passwoid }; 

The evsAuthschemeManuaiBasic s^^me Can be registered for any realm by using 
the ewsAuthRegister function. The scheme field of the EwsAuthorization parameter 
must be set to ewsAuthschemeManuaiBasic, and the application handle can be set in 
the handle field. The params field is not used by the manual basic scheme. Manual 
basic can only be registered once per realm. If there are "non-manual" 
(ewsAuthschemeBasic) Bastc authorization entries registered to the same realm as a 
manual Basic entry, the "non-manual" authorization entries will be given preference. 
If no "non-manual" authorization entries match the request, then ewaAuthCheckBasic 
will be called. 

The EmWeb/Server will invoke the application's ewaAuchchecksasic function when 
authenticating a request for a realm protected by the manual basic scheme, unless 
a "non-manual" basic authorization entry matched. The application's 
ewaAuthCheckBasic function must now determine whether or not the authorization is 
valid. This function is passed the context, requested document's realm, and the 
base64-encoded basic cookie from the Authorization header (as specified in RFC 
2068). If the build option ew_config_option_auth_mbasic_decode is defined, then 
useiNaoe and passvozd Will polnt to the usemame/password strings decoded from 
the basiccookie, Otherwise these pointers are null. Ali strings are null terminated, 
and should not be modified by the application. 

The return value from ewaAuthCheckBasic determines how the server will respond to 
the request. If false is returned, access will be denied, if true is returned, access 
will be granted . 

Optionally, the application can suspend the context.from within ewaAuthCheckBasic 
using ewssuspend. Em Web/Server will ignore the return value In this case. When the 
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context Is later resumed by ewsResume, the ewaAuthcheckBasic function will be 
reinvoked by EmWeb/Server. 

The application may abort the context from within ewaAuthchecksasic by calling 

evsNecHTTPAboit. 

4.1.4.3. Digest Authentication 

The Digest authentication scheme challenges the browser client using a "nonce" 
value. The client responds with a valid cryptographic checksum of the usemame, 
secret password, the given nonce value, the HTTP request method, and the 
requested URI, This avoids sending the secret password over the network. 
Furthenmore, by generating unique nonce values, the server can make replay and 
other forms of attack impractical. 

Note: EmWeb's digest authentication support Is derived from 
the RSA Data Security, inc. MD5 IViessage-Digest Algorithm. 

Note: Digest authentication is currently an internet proposed 
standard and is not yet supported by many browsers. 

The authentication parameters for Digest authentication include the usemame and 
password represented as null-terminated character strings. In addition, one 
addition£Ll boolean parameter is defined as follows: 

digestRequired 

If TRtJE, the Em Web/Server will require that the client provide a valid 
message digest to prevent forgery of the request message. This requires 
significantly more computation and is not supported by most browsers. 

The application is required to define the application-specific structure called 
EvaAuchNonce. The EvaAuthNonce Structure is application-specific and contains 
parameters to be used in calculating (via MD5 hash of the structure's contents) a 
unique nonce value. We recommend including the client's IP address, timestamp, a 
server-wide secret key, and any other random bits the application desires. 

Two additional functions must be provided by the application for the generation and 
verification of nonce values as follows: 

First, the ewaAuchwoncecteate o function is called by EmWeb/Server in response to 
an unauthenticated request for a document to request that the application initialize 
the EwaAuttiNonce Structure. 

void 

evaAuChNonceCreaCe 

(EwsContexc context: 
, const chai •realm 
.EwaAuthNonce *noncep ); 
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The application should initialize the EwaAuthNonce structure. The request context 
and reaim are provided as inputs. For example, a typical application could read the 
application-specific network handle from the request context to detemiine the dienrs 
IP address. 

Second, the ewaAuchuoncechecko function is called by Em Web/Server in response 
to a client's request to authenticate against a nonce value previously initialized by 

the application In ewaAuthWonceCteate o , 

typed ef enum EwaAuthNoncestatus e 

I 

ewaAuchNonceOK, /• nonce value valid for request •/ 

evaAuthNonceLastOK, /• nonce value valid, but von't be again */ \ 

ewaAuthNonceSCale, /* nonce value is stale, generate new nonce •/ 

ewaAuthHonceDenied /• nonce value is invalid •/ 
} EvaAuthNonceStacus; 

EwaAuthNonceStatus 
ewaAu thJJonceCheck 

(Evsconcexc context ' 

, const chaz « realm 

.EwaAuthNonce *noncep, uintf count ); 

This function is calied by Em Web/Server to verify that the nonce is valid for the 
cun-ent request. The count parameter indicates the number of times this nonce has 
been used previously (i.e. zero on the first call). The application may decide to 
accept the nonce by returning evaAuthwonceox or ewaAutn^onceLastOK. The 
evaAuthNonceLastOK Is used to Signal to the server that the nonce value is valid this 
time, but will not be valid if used again. The server uses this information to generate 
a new nonce and pass a next nonce value to the browser to be used on the next 
request. Otherwise, the application may decide to expire the nonce (because it has 
been used loo many times, because too much time has gone by since was created, 
or any other reason that the application decides) by reluming ewaAu thuoncestaie, or 
refuse to authenticate (because the client iP address doesn't match) by returning 

evaAuthNonceDenied, 

4.1.4.4. Manual Digest Authentication 

For some applications, it may be impossible to obtain the digest authentication 
username/password pairs prior to receiving requests for a document. Instead, the 
digest authentication username/password may be stored on a remote server. This 
server would need to be queried for the usemame/password as each request 
requiring authentication is processed. 

In order to support this, a special type of authentication scheme Is defined: 
ewsAuthscheaneManuaiDigest. ThIs scheme Is available only if the build option 
Ew_coNFiG_opTioN_AtJTH__MDiGEST Is defined. Once defined, the application musl 
provide the following interface: 
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boolean evaAuthCheclcDigesc ( EwsConcext context 

, const chai *iealin 
, const EwaAuchNonce *noncep 
.const cliai *useiMaine 
.const char ••digest ); 

The ewsAuthschemeKanuaiDigest scheme Can be registered for any realm by using 
the ewsAuthRegister function. The scheme field Of the EwsAuthorization paranneter 
must be set to ewsAuthschemeKanuaiDigest, and the application handle can be set in 
the handle field. The paxams.digest.digestRequiied flag may be used if the 
Ew_coNFiG_opTioN_AirrH_DiGEST_M buIld option is defined. All other parameters are 
noTused by the manual digest scheme. Manual digest can be registered once per 
realm. If there are "non-manuaf" (ewsAuthschemeoigest) digest authorization entries 
registered to the same realm as a manual digest entry, the "non-manual" 
authorization entries will be given preference. If no "non-manuai" authorization 
entries match the request, then ewaAuthchecicDigest will be called. 

The EmWeb/Server will lnvol<e the application's ewaAuthcheckcigest function when 
authenticating a request for a realm protected by the manual digest scheme, unless 
a "non-manual" digest authorization entry matched. The application's 
ewaAuthcheckDigest function must now determine whether or not the authorization 
is valid. This function is passed the context, the requested document's realm, the 
nonce associated with this request, and the usemame as it appears in the request 
All strings are null terminated, and should not be modified by the application. 

ewaAuthcheckDigest retums a boolean status that determines how the sealer will 
respond to the request. If false Is retumed, access will be denied. If true is returned, 
the • digest parameter has been set to a null terminated string containing the ASCII 
string representation of the MD5 checksum of the usemame, realm, and password 
strings. This is refen-ed to the H(A1) value in RFC 2069. For example, If the 
username Is "user*, password is "password", realm is *foo_reaim", then *dige5t 
should be set to the string representation of MD5( usenfoo_realm:password ), which 
would be: 

♦digest • ''ea£d9339d0ll4895926c24ec79af72ll" 

The *digest value Is used by the server to validate the response digest and entity- 
digest that are present in the request's Authorization header. If the validation does 
not pass, access will be denied. The memory used by the ^digest value will remain 
referenced by the server until the context of the request is freed. 

Optionally, the application can suspend the context from within ewaAuthcheckDigest 
using ewssuspend. The return value will be. Ignored, When the context Is later 
resumed with ewsResume, the ewaAuthcheckDigest funcUon wll! be relnvoKed. 

The application may abort the context from within ewaAuthcheckDigest by calling 

ewsNetHTTPAboit. 
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4.1.4.5. Application Security Verification 

Some applications may provide their own proprietary form of client authentication. 
These proprietary methods will vary from application to application. For example, an 
application could use the client's IP address to restrict the client's access to certain 
realms. 

EmWeb provides a generic interface that allows an application to provide any 
proprietary checks on the request context and requested reaJm. This fnlerface 
allows the application to deny service to the client if so desired. 

This interface is made available by defining the rw_coNriG option aute vekify 
build option. The application must then provide the following interfaceT 

boolean ewaAuthVeiifySecuiity ( Ews Con text context 

.const char •lealrn ); 

This function is called by EmWeb/Server after the current request has passed the 
standard authorization procedures described above, For example, If basic 
authentication is enabled on a realm, ewaAuthveiifysecuri cy will be called only after 
the basic authentication successfully completes. If digest authentication is used, 
then ewaAuthVeiifySecuiity IS called after the response digest is successfully 
verified, but before the entity-digest is checked {if the 
Ew_coNFiG_opTioiJ_AUTH_DiGEST_K build Option Is tumed on). 

ewaAuthverifysecuiity Is passed the current context, and a pointer to a null 
terminated string containing the realm. The application can allow the request to 
complete by returning true from evaAuthVeiifySecuiicy. If evaAuthVeiifySecurity 

returns false, the request is denied access. 

ewaAuthVeiifySecuiity Is provided only as a secondary security mechanism, and 
can only be used in conjunction v^th a defined standard security scheme, such as 
basic or digest 

Optionally, the application can suspend the context from within 
ewaAuthVeiifySecuiity uslng evssuspend. The return value will be ignored. When 
the context is later resumed, the ewaAuchver if ysecuri ty function will be reinvoked. 

The appl icatio n may abort the context from within ewaAuthveiifysecuiicy by calling 
ewsNetHTTP Abort. 

4.1,4.6. Document Realm Assignment 

The authentication realm of a document is typically determined from the _access 
configuration files by the EmWeb/Compller. However, tt may be desirable to change 
the document's realm assignment at run-time. The following function is optionally 
provided by the EmWeb/Server to the application for this purpose: 

EwsStatus evsDocumentSetRealm ( const chai •uil, const char -lealm ) ; 
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This function returns' ews_status_ok on success, or ews_status_not_found if the 
specified local URL is not installed, or ews_status_no_resources it insufficient 
resources were available to create a new realm. 

4.1.5. Request Context Access 

Each HTTP request received by the EmWeb/Server is assigned a unique context. A 
context handle of type Evscontexc is first returned to the application from the 

evsMecHTTPSCirc function. 

Application code responsible for the run-time content of HTML documents (i,e. C code 
fragments from <ekweb_string> and <emweb_include>, HTML form processing 
functions ewaFoimserve_* and ewaFormsubmi t_« , and raw CGI interface functions 
ewacGistarc^* and ewacGiData_*) have access to the corresponding HTTP request 
context, in the case of <emv7eb_string> and <emweb_include> C code fragments, the 
context is available from the local variable symbol ewscontexc. In the case of the fomi 
and raw CG) processing functions, the context is passed as a parameter. 

Several context access functions are defined which can be called by the application to 
extract information about the current context. For example, the function: 

EvaNecHandle ewsConcextNetKandle ( EvsConcexc concexc ) 

Returns the network handle con^esponding to the HTTP context that was passed by 
the application to the EmWeb/Server in the ewsNecHTTPstaic function. The following 
table lists these context access functions: 



Context Access Function 


Description 


ewsContexcNecHandle 

evsContexcNecHandle ( EvsConcext concexc } ; 


Returns the network handle that 
was passed by the application to 
EmWeb/Server in the evsiietHTTP- 
staic function.. 


EwaDocumentHandle 
evsConCextDocumentHandle 
( EwsContexC context ) ; 


Returns the document handle that 
was passed by the application to 
EmWeb/Server in either the evs- 

DocumencRegistei Or ewsDocumenc- 

Clone functions, or 

EWA_DOCUMENT_HANDX.E_NULL. 


EvraAuthUandle 
evsConcexCAuchHandle 
( Ewscontexc concexc } ; 


Returns the authorization handle 
that was passed by the application 
to EmWeb/Server in the ewsAu- 

chRegister function, or 
EWA_AUTH_HANDLE_NULL. 



Copyright Q 1997 Agranat Systems, inc. Page 48 

SUBSTITUTE SHEET (RULE 26) 



REV. 6/20/97 



wo 98/06033 

EmWeb*^^ Functionai Specification 



-11- 
ConfidentiBi 



PCT/US97/13ai7 



EmWeb/Server 



Context Access Function 


Description 


boolean 

evs Context! sResuming 
( £wsContext context } ; 


Returns true i( this is the first appli- 
cation cali-out after a suspended 
request was resumed by calling 
evsResutne. Otherwise, returns 

FALSE. 


uint32 

ewsContexclteiBtions 


Returns the iteration count (start- 
ing with zero) to an 

<EMWEE_STR1NG> Or 

<E^MEB_XNCLUDE> C code fragment 
with the EMWEB^iTERATE attribute 
specified. 


uintf 

ewsContextDate { EwsContext context, 
char -datap, uintf length ); 


Copies the HTTP Dace : header 
into the buffer provided by the 
application and returns the actual 
number of bytes present. 


uintf 

ewsContextPxagna ( EwsContext context, 
char "datap, uintf length } ; 


Copies the HTTP Pragma: header 
into the buffer provided by the 
application and returns the actual 
number of bytes present. 


uintf 

ews Con text From { EwsContext context, 
char '*datap, uintf length ) ; 


Copies the HTTP From: header 
Into the buffer provided by the 
application and returns the actual 
number of bytes present. 


uintf 

ewsContextl f Modi f i edSince 

{ EwsContext context, char *datap, uintf 

length ) ; 


Copies the HTTP if -modified- 

since : header Into the buffer pro- 
vided by the application and 
returns the actual number of bytes 
present. 


uintf 

ewsContextRef eiei ( EwsContext context, 
char *datap. uintf length ); 


Copies the HTTP Ref erei : header 
into the buffer provided by the 
application and returns the actual 
number of bytes present. 


uintf 

ews Con t ex tUser Agent ( EwsContext context, 
chaz •daup^ uintf length ) ; 


Copies the HTTP user- agent i 

value into the buffer provided by 
the application and returns the 
actual number of bytes present. 
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Context Access Function 


Description 


uintf 

ewsCon&extHosc ( Ewsconcexc contexc, chai 
•datap, uincf length ); 


Copies the HTTP Host: value into 
the buffer provided by the applica- 
tion and returns the actual number 
of bytes present. 


umci 

evsCGZServezPxococol ( EvsContexc context, 
char * da cap, uintf length ) ; 


oopies me n i i r* server protocol 
"http/i. o" or "Hrrp/0.9" Into the 
buffer provided by the application 
and returns the actual number of 
bytes present. 


uintf 

evsCGIReques tMechod ( EwsContext context, 
char "da tap, uintf length ) ; 


Copies the HTTP request method 
"get", "head", or "post Into the 
buffer provided by the application 
and returns the actual number of 
bytes present. 


const char • 

ewsCGIPathInfo( EwsContext context }; 


Returns pointer to CGI extra path 
information if present, or NULL. 


const char • 

evsCGISciiptName( EwsContext context }; 


Returns pointer to URL base path 
string. 


uincf 

ewsCGIQueryString ( EvsContexc context, char 
*aatap, uinti lengwii f. 


Copies the URL query string into 
the buffer provided by the applica- 
tion and returns the actual number 
of bytes present 


uintf 

ew5CCIContencType( EwsContext context, char 
•dacap, uincf length }; 


Copies the HTTP content - type : 

value into the buffer provided by 

mc appiicauun onu icium^ inc 

actual number of bytes present. 


uincf 

ew5CGIContentLengch( EwsContext context ); 


Returns the value of the HTTP 
concenc-iengch: header or zero if 
not present. 


uintf 

evsCGIConcencEncodingt EvsContexc concexc, 
chai *datap, uintf lengch ); 


Copies the HTTP concent -encod- , 

ing: value into the buffer provided 
by the application and returns the 
actual number of bytes present. 



Note that the context access functions that copy values into application-provided 
strings return the actual number of bytes in the value. If the value is not present, then 
these functions return zero. These functions do not ovenvrite the application buffer 
(i.e. the lengch parameter Shall be honored by EmWeb/Server). However, the function 
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may return a number greater than the length if the application buffer was not large 
enough to accommodate the value. In fact, the length parameter of zero may be used 
to determine the size of the buffer needed. 

4.1.6. Raw CGI 

We believe that one of the greatest features of EmWeb/Server is that the system 
integrator can implement nearly any embedded Web-based application without using 
CGI. 

While Agranat Systems strongly discourages its use, we recognize that some highly 
sophisticated applications may require a raw CGI interface, and so we provide one. 

A URL corresponding to the base name of a CGI script may be specified in the _access 
file which Is processed by the Em Web/Compiler. The application must provide two 
functions for each CGI script with names derived from the value of the cgi' symbol 
directive in the _access file as follows: 

EwaCCIHandie ewaCGIStait_syrabcJ ( Ewsconcext context ) ; 

This function is called by EmWeb/Seiyer when a CGI script Is first requested by a Web 
server. The application returns a handle that is passed baci< to the application in the 
second function: 

void evaCCIData_s>7JibcJ { EwaCCIHandie handle, EwaNetBuffei buffei ); 

This second function is called by EmWeb/Sen/er to pass one or more buffers to the 
application containing raw CGI data (i.e. the HTTP message body) as they are 
received from the networit. The application is responsible for knowing where the end 
of data is from the content - length: header (available from evscciconcentLength). 

Restriction: The application's ewacciData^symboJ function 
must not attempt to access request header Information from 
the request context because the network buffer(s) containing 
request headers may have been discarded. Any information 
needed by the application should be copied and saved during 

e wa CG I S ta r t__symb o J , 

The application may generate a standardized HTTP response header by invoking the 
following function: 

EwsStacus evsCGISendScacus 
( EwsContext context, const char ♦ status, const char *string) ; 

This function sends an HTTP status line for the appropriate HTTP version. The status 
argument must contain a null-tennlnated character string containing a three-digit 
HTTP status code followed optionally by descriptive status text. If not NULL, the string 
argument contains a null-terminated character string containing additional headers, 
andl/or data. This function returns ews_status_ox on success. Otherwise, an en-or 
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code (ews_status_bad_state or ews_status_no_resources) is returned. Note that if 
ewsCGisendscacus Is to be used, tt must be used only once per request, and must be 
used before cading evsccisaca . 

For example, to send a simple HTML page:- 

ewsCGisendscacus ( context, "200 OK", 
"CoiiCenc-Type : cexc/hcmlSr\n" 
"Concent -Length; 66\r\n" 
*'\r\n" 

" <HEAD> <TITLE>Exainple</TITLE> < /HEAD> " 
"<BODY>This is an example</B0Dy>" ); 

The application may send additional headers followed by a message body by invoking 
the following function: 

Evsstacus ewsCGIOata ( EwsContext context, EwaKetBuffei buffer ) ; 

This function sends the chain of buffers to the Web browser. Note that the application 
must delimit the header and body sections with a blank line sequence in accordance 
with the HTTP specification. To coriiplete the request, the application should invoke 
this function with an ewa_net_buffer_null buffer descriptor. This causes Em Web/ 
Server to close the connection. This function returns ews_status_ok on success. 
Otherwise, an error code (ews_status_bad_state) is returned. 

Instead of sending headers and data, the application may instruct EmWeb/Server to 
generate a redirect to a specified URL or. if local, serve a local document as a 
response. To send a redirect response to the browser (for a local or remote document) 
the application may invoke the following function: 

Ewsstatus ewsCGIRediiect ( EwsContext context, const chaz * uzl ) ; 

To serve a local document as a response, the application may invoke the following 
function: 

Ewsscatus ewsConcextSendReply { EwsContext context, chai • uil ) ; 

Note that these functions may not be used in conjunction with ewsccicata or 
ewsCGisendstatus. The url parameter may be a relative or absolute URL 

Several CGI environment values are available from the HTTP request context as 
outlined In the Context section above. In addition, the following two functions return 
global server information for conformance with CGI/1 .0: 

const chai • ewsCGIServexSof tvaxe ( void ) 

Returns the server software version string, for example "Agianat-Emweb/Ri_o''. 

const char * ewsCGIGatewaylnteiface ( void ) 
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Returns the gateway Interface version string, for example "cgi/i , o". 
4.1.7, Logging Hook 

The application may optionally provide the following function (or macro) for logging 
HTTP events: 

void ewaLogHook(EwsContext context, EwsLogStatus status); 

This function is invoked by EmWeb/Server at least once for each HTTP request, and 
possibly a second time for certain dispositions after a successful request. Possible 
status values include (from sic/inciude/ews_de£ .h) : 

typedef enum EvsLogStatus_e 



{ 



• 200 Request accepted 



EWS LOG STATUS OK, 



Reguesc dispositions (afcez successful lequest) 



EWS_LOG_STATUS_KO_COHTEIIT . 
EWS_LOG_STATUS_M0VED_^PERKANENTLV , 

ews2log~status~moved~temporarily , 

EWS_LOG_STATUS_SEE_OTHER , 
EWS_LOcJSTATUS_NOT_MODIFIED , 



/* 2 04 no-op toim oz ima 
/• 301 link •/ 
/• 302 ledirect */ 
/• 303 see other •/ 

/• 304 not modified sine 



• 401 Unauthorized 

EWS_LOG_STATUS_AUTH_FAH.ED , 
EWS_LOG~STATUS_AUT}i~FORCERY , 
EWS_LOG_STATUS_A\rrH_STALE , 

ews_log2status_auth_reouired, 

EWS log"status auth~digest_reouired. 



/* authoiization failed 
/* had message checksum 
/* authorization nonce s 
/• authoiization not pie 
/* message digest not pz 



400 Bad Request 



ews_log_status_bad_reouest , 

EKS_LOGjsTATUS_BAD_rORM , 

ews_log~status~bad_imagemap , 
• Additional eiiois 



/* HTTP parse error •/ 
/* form data parse error 
/* imagemap query parse 



EWS_LOG_STATUS_MOT_rOtJND, , 
EWS_L0G_STATOS_KETH0D_^KOT_AIX0WED , 

ews_log_status"length~reouired , 
ews_log~status_unavailable , 

EWS LOG^STATUS NOT_IMPLEMENTED , 



/* 404 not found oi hidd 

/•■405 method not allowe 

/• 411 length required • 

/• 503 aborted Document 

/• 501 bad method for UK 
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EWS_LOC_STATUS_NO_RESOURCES , 
EWS LOG^STATUS INTERJJAI, ERROR 



/" 500 insufficient leso 
/" 500 incernal erioj •/ 



) EwsLogScatus; 



4.1.8; Local Filesystem Interfaces 

The EmWeb Server provides the ability to manage a fiiesystem on the serving system. 
The Server supports: 

• uploading a file from a client (browser) to the server 

- serving the contents of a file in response to a URL GET 

in both cases, the filesystem is external to the EmWeb Server. EmWeb assumes 
nothing about the implementation of this fiiesystem; it can exist on a local disk, non- 
volatile memory, or on an external proxy. All EmWeb requires is the ability to: 

- retrieve/set meta-informatton about the file (e.g., type, size, modification time, etc.). 

- open a file 

- read a number of bytes from a existing file 

- write a nuniber of bytes to a newly created file 

- dose a file. 

The API that must be supplied to EmWeb to provide these functions Is defined below. 
To enable the basic file support, define the preprocessor symbol 

EW__CONFJG^OPTION_FILE In ew^^conf ig . h. 

4.1.8.1. The EwsFiieParams structure 

The EwsFiieParams stTUCture is defined in the ews^sys .h include file. It is used by the 
EmWeb server to associate meta-information with a local file. The EwsFiiePaxams 
structure consists of a union of two substructures. These substnjctures correspond 
to the file function that EmWeb is to perform. The fiieFieid structure is used when 
the browser is uploading a file to the server via a form post (see RFC1B67). The 
f iieinfo Structure Is used to serve a file in response to a get for a particular URL. 
The Individual fields for each of these structures is described in the description 
associated file operation. 

cypedef union EvsFileParam5_s 
I 

/• 

♦ fiieFieid - foi support of the form INPUT TYPE-FILE field. 

* The server fills out this structure, and passes it to 

• the application when the file is submitted 
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*/ 

t ifdef EW_CONFIG_OPTION_FIELDTyPE_FILE 
sciucr 
{ 

const chai •fileName; /* file name or NULL »/ 

const chai *contentType; /• MIME type •/ 
const char •contentEncoding; /• content encoding or NULL •/ 
const chai *contentDisposition; /* Content •disposition: •/ 
int32 contentLength; /* length oi EWS_CONTEKT_X-ENGTH_UNKNOWN »/ 

J fileFieid; 
# endif /* EW CONFIG_OPTION_nEU>TYPE_FILE */ 



• filelnfo - for support for local file operations (GET, HEAD, OPTIONS, 

• PUT, DELETE) . This structure is setup by the application vhen a URL 

* that corresponds to a local file is received. This structure 

* gives the server all it needs to know to handle the file operation. 
•/ 

« if defined ( EW_CONFIG_0PTION_FILE_GET ) 
Struct 
{ 

EwaFileName fileName; /• file name (opaque) */ 

const chai *contentType; /" MIME type •/ 

const char «contentEncoding; content encoding or NULL •/ 

const char ♦contentLanguage; /• content language oi NULL */ 

const char 'eTag; /• HTTP/1.1 cachability tag, oi NULL •/ 

const char "lastModif ied; /• modification time (RFcai23) or NULL •/ 

const char *la5tModif iedi036 ; /• modification time (RFC1036) or NULL •/ 

const chai *realni; /* auth realm oi NULL */ 

int32 contentLength; /* length oi EWS_CONTENT_LENGTH_UNKNOWN •/ 

EwsRequestMethod allow; /« alloved methods •/ 
/• HEAD & OPTION _alvays_ alloved by default •/ 

] filelnfo; 

char leservedi; 

) EwsFileParams, *EwsFileParamsP; 

4.1.8.2. Fiie Upload 

Support for Rie Upload Is enabled In the EmWeb server by defining the preprocessor 

symbol EW_C0NFIG_OPTIOH_FIELDTYPE_riLE In ev_config.h. 

To support tile upload, EmWeb supports the methods described in RFC1867 (Form- 
based File Upload in HTML). At the time oJ this writing, only Netscape Navigator 
implements this RFC. For more infonmation about RFC1867 and file upload 
support, contact Agranat Systems. 

RFC1857 describes a new form Input field of type-file. This form field results In an 
input field that allows a user to enter a filename. This filename is the name of a tile 
that is accessible by the browser. On submission of this form, the browser reads the 
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file, and sends the file's contents to server as part of the post request. 
This file field takes the following form: 

<IHPUT TYPE -FILE NAME •name VALUE -value> 



Where name Is the name of the form field and value is the default filename to display 
in the form when It is first served. When the EmWeb/Compiler encounters one of 
these fomi fields, the folioviring form structure fields are generated: 

chnr *namei 
SwaFi leHandle name^handle ; 

The name field is used by the form serve function only, it allows the application to 
override the default file name given when the form is first displayed (note: some 
browsers do not support a default value - call Agranat Systems for more information). 
The name_handie field is used by the forni submit function only. It provides the file 
handle for the submitted file (see the discussion of ewariieposc below). The status 
forname_handie is set to (ew_form_returned ) Ew_FORM_DYNAMi c) on successful file 
POST, else ew_form_file_error. 

When EmWeb receives the submitted file, it allocates an EwsFiiep&iams structure 
and Initializes the f iieFieid substnjcture. The tiieFieid substructure is setup using 
the optional file headers that are sent along with the file. The fiieFieid fields are: 

fileName 

Null temninated string containing the name of the file. This is usually 
supplied as the basename of the file (no path information). This field will be 
a NULL pointer if the browser does not supply a filename. 

contentType 

Null terminated string containing the value ol the content -Type header, or 
a NULL pointer if the content -Type header is not present (assumed to be 

text/plain). 
contentEncoding 

Null terminated string containing the value of the content -Encoding header, 
or a NULL pointer if the content -Encoding header is not present. 

contentDispositton 

■ Null terminated string containing the value of the Concent -Disposition 
header, or a null pointer if the content -Disposition header Is not present. 

contentLength 

set to the number of bytes in the file to be posted. If the concent • Length 
header is not supplied by the browser, then this field will be set to 
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EWS_COKTEJn*_LEMGTH_UHKHOWN . 

As soon as EmWeb receives the submined form containing an ii:put type- file field 
with file content, prior to calling the application's submit function, a call wili be made 
to the application interface ewaFilePost: 

EwaFiieHandle evaFilePost( 

EvsContexc context, 

const EwsFilePaiams •paiams ) ; 

This function is provided by the application. The application defines the appropriate 
type for EwaRleHandle, and the value for ewa_file_haki>le_null, which indicates a 
NULL EwaFiieHandle. The paiams parameter is initialized by Em Web as described 
above, and released by EmWeb on return from ewaFiiePost. 

ewaFiiePosc should Open a file, and return a EwaFiieHandie value that uniquely 
identifies that file. On en-or. evaFiiePost can return EWA_riLr_ri-j;DLE_NULL, which 
will cause EmV^eb to discard the contents of the submitted file without discarding the 
other submitted form fields. The application can also call ewssuspend to suspend the 
cument contejct. In this case. ewaFiiePost m\\ be reinvoi<ed (with 

ewsContexclsResuiring (context) TRUE) Once the application CallS ewsResume On 

the context. The request can be aborted and the connection closed if ewariiepost 

invokes ewsNetHTTPAbort, 

After ewaFilePost is called, EmWeb will start calling the file write routine: 



sintf ewaFileWiite( EwsContext context, 

EwaFiieHandle handle, 
const uinte 'dacap, 
uintf length ) ; 

handle is set to the value that was returned by the ewariiePost call, datap is a 
pointer to the data to be written, and length Is set to the number of bytes that can be 
written from datap. cwaFiiewiite returns the number of bytes written, or < o if an 
error occurred. If < o is returned, EmWeb wili discard the rest of the incoming file 
without discarding the other submitted form fields. The application can suspend the 
current context by calling ewssuspend from within ewariiewrice and returning the 
number of bytes written prior to suspending (can be zero). The application can then 
resume the context by calling evsResume, This will cause ewaFiiewrice to be 

reinvoked Vflth ewsConcextlsResuBiing ( context ) TRUE and datap and length 

adjusted by the number returned by the suspended call to ewsFiiewiite. The 
application can also call ewsNetHTTPAboit to abort the entire request, and dose the 
connection. 

After the entire tile has been received and written, the application's form submit 
function will be called. If the status field has been set to Ew_FORK_RETURiiEr), then the 
name handle contains the file handle lor the file as returned by ewariiePost. It is the 
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responsibility of the form submit function to close the file at this point 

Note well that once a file handle Is returned by ewariiepost, it is the responsibility of 
the application to dose that file handle during the form submit function. EmWeb/ 
Server will close the file handle If the request is aborted prior to calling the submit 

4.1.8.3. File Serve 

The EmWeb Server allows an application to provide a file externa) to an EmWeb 
archive for the response to a get request This functionality is enabled by defining 
the preprocessor symbol ew_config_option_ftle__get in ew^conf ig . h. 

To serve a file, an application must "mark" a get request URL as representing a non- 
archive file. Once this is done, the EmWeb Server will "open" this file, read data from 
it and serve this data in response to the URL get. After all data is served, EmWeb 
Server will close the file. 

To "mark" a URL as a local file, the application calls the server interface 
ewscontexcsetriie during bURLget: 

Ewsscacus evsconcexcSecFile( Ew'sConrexc contexc, 

EwsFileParamsP paiams ) ; 

ewscontextsetFile can be called from; 

- evaURLHook once the URL is determined to be a local file entity. 

- an application's form submit function prior to calling ewscontextsendRepiy. In this 
case, the URL passed to ewscontextsendRepiy represents the local file to be served. 

Note that both the evaURLHook and an application's form submit function can suspend 
the current context using ewssuspend. This allows the application to do any 
asynchronous tasks needed prior to calling ewsconcextsecFiie. 

The f iieinf o substructure of the paiam parameter must be set up by the application 
prior to calling ewscontextsecFiie. This stmcture gives EmWeb Sen/er all the 
Information about the file it needs in order to serve the file as response content. The 
fields are described be\ovr. 

EwaFileName lIleName 

This field is for use only by the application, EmWeb Server ignores this field. 
The type EwaFileName must be specified by the application. 

contentType 

set to a NULL terminated string containing the value for the content -Type 
header that Is to be sent with the file. 
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contentEncoding 

set to a NULL terminated string containing the value for the concent - 
Encoding header that is sent with the fiie. if a null pointer, no concent - 
Encoding header is sent. 

contentLanguage 

set to a NULL terminated string containing the value for the content - 
Language header that is sent wilii the file, if a null pointer, no content - 
Language header IS sent. 

eTag 

reserved, must be set to null. 
lastModified 

the last modification date of the fiie in RFC11 23 formal as a null terminated 
string. If NULL, it is assumed that the file should be served each time it is 
requested. 

lastModified 1036 

the last modification date of the file in RFC 1 036 formal as a null terminated 
string. Some browsers cannot con"ectly recognize the RFC1 123 format, so 
this field should be set In addition to the lastModified field. Call Agranat 
Systems for more information. 

realm 

the realm the request should be authenticated against for this fiie as a null 
temiinated string, eise null If no authorization required. Authorization is 
only checked when the file is served as a result of calling ewsConiextSetFiie 
from ewaURLHook • the realm used to protect the form submission is used 
implicitly when serving the file as a result of a ewsContextSendRepiy. 

contentLength 

Set to the number of bytes in the file, else ews_content_length_unknokn if 
the file's length is unknown. 

allow 

reserved, must be set to evsRequestMethodGet. 

EmWeb/Server references the paiam parameter for the duration of the file operation. 
As such, this parameter must be accessible throughout the life of the request • 
beyond the context of the evacontextsetriie call. It can be safely deallocated by the 
application during the evaNecHTTPcieanup call. 

Once the URL has been "marked" by the ewscontextsetriie call, EmWeb/Server 
will open the file using the evari lecec interface: 
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EwaFileHandle ewaFileCett EwsContext contexc, 

const char "url, 
const EwsFilePazamsP paxams ) ; 

The uii parameter is the URL that was "marked" as a file access, params Is the 
EwsFiieParams Structure that was passed to evscontextsetriie. The application 
defines the appropriate type for EvaFi leHandie, and the value for 
EWA_nLE_HANDLE_NULL, whlch indicates a null Ewari leHandie. 

evaFiieGet should Open the file identified by paiams and uri, and return a 
EvaFi leKandie that Uniquely represents the file. On error, ewaFiiecec can return 
EWA_riLE_HwroLE_NULL. This causes the connection to abort. If desired, the 
appTication can suspend the current context by calling ewssu spend from within 
evaFiieGet. The context can be resumed at a later time by calling ewsResume. 
evaFiieGet Will be rein V0i<ed (with evs Con text I sResuming ( context ) TRUE). 

Once the file has been opened by ewaFiiecet, Em Web/Server will read the file by 

calling ewaFileRead: 

sintf ewaFileRead ( EwsContext context* 

EwaFileHandle handle, 
uince *datap-, 
uintf length ) ; 



This function should copy up to length bytes into the area of memory starting at 
datap, handle is set to the file handle returned by ewaFiiecet. On retum, 
ewaFileRead should retum the number of bytes written into datap, which can be less 
than length. On error, < o should be returned {this causes the request to be aborted 
and the connection dose). This function can suspend by calling ewssuspend and 
returning the number of bytes written into datap (can be zero). When the file 
described by handle has been completely read, this routine must return zero. 
Returning zero indicates that End-of-File has been reached (except when 
ewssuspend has been called prior to returning). 

Once all file data has been read, Em Web/Server will close the file by calling 
ewaFileClose: 

void evaPileClose < EwaFileHandle handle, EwsStatus status ); 



ewaFileClose should close the file associated with handle (the Ewsrilepaiams 
Structure can be safely deallocated at this point), status will be set to ews_status_ok 
on successful completion of the file serve, otherwise it will be set to an error code. 
EmWeb/Server will call this function to close a file handle during an aborted request 
prior to calling ewaNetHrrpEnd. Note that this function does not support suspension. 
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4.2. Application Interface Examples 

This section is Intended to Illustrate the use of application interface functions under 
various scenarios. 

The following tables Illustrates the application interlaces used in the simplest EmWeb/ 
Server configuration. 



Application->Server 
(Initialization) 


Server -> 
Application 


Description 


evsini C 


evaAlloc 

t 4 t 


Application initializes EmWeb/Server. 
The server may allocate run-time 
memory resources. 


evsSocumenclnscall^i - 
chive 

ewsAuthRegister 


ewaAlloc 

• • • 


Application installs one or more docu- 
ment archives and registers zero or 
more authenticated users. The server 
allocates run-time memory resources 
for its internal databases. 



AppIication->Server 
(HTTP Transaction) 


Server -> 
Application 


Description 


ewsNetHTTPScait 


ewaAlloc 

• * * 


Application accepts a new HTTP TCP 
connection request and informs the 
EmWeb/Server. The server allocates 
memory resources for the request. 


ewsJJetHTTPReceive 

f i 1 


eva Alloc 

« • * 

evaNe tBu f f e i Fi ee 


Application accepts request data from 
the network and passes tt to the seiver 
for processing. The server may allo- 
cate memory resources to process the 
request as needed. Some network 
buffers received may be released at 
this point. 
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App)ication->Server 
(HTTP Transaction) 


Server -> 
Application 


Description 


evsKun 


<EMWZB_STR1NG> 
< £tlWEp_INCXuSE > 

ewaForinServe_* 
ewaFormSubmi t_* 
ewaCGIScar t_» 
ewaCGIDa ta_* 

• ■ > 


The server invokes the application 
code attached to the requested docu- 
ment in order to construct a response 
on-the-fly. 




ewa}}etBuff«i Al- 
loc 

* • * 

e vaNe cHTTPSend 
(STATUS_OK) 


The server allocates network buffers 
as needed, fills them with HTTP 
response data, and sends them to the 
application for transmission. 




ewaFree 

ewaNetSuf feiFzee 

* • < 

ewaNecHTTPEnd 


The server releases any remaining 
resources associated with the HTTP 
transaction and terminates the 
request. The application closes the 
TCP connection at this point. 


The next table illustrates a typical HTTP transaction during whicfi the application 
instnjcts the EmWeb/Ser^er to yield control of the CPU. 


Application->Server 
(Scheduling) 


Server -> 
Application 


Description 


ewsNecHTTPStaiC 


ewaAlloc 

1 » 1 


Application accepts a new HTTP TCP 
connection request and Informs the 
Em Web/Server. The server allocates 
memory resources for the request. 


ewsNetHTTPReceive 

4 W * 


evaAlloc 

4 * > 

evaNe tBiif £ ei Fi e e 

• • • 


Application accepts request data from 
the network and passes it to the server 
for processing. The server may allo- 
cate memory resources to process the 
request as needed. Some network 
buffers received may be released at 
this point. 


ewsRun 


<EMWEB_STRING> 
<EMWEB~INCLUDE> 
eva Forms eive_* 
ewaFormSubBiic_* 

* * • 


The server invokes the application 
code attached to the requested docu- 
ment. 
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AppIication->Server 
(Scheduling) 


Server -> 
Application 


Description 


evssu spend 




The application suspends the request. 
Processing on the request stops until 
resumed. 




<EMWEB__STRING> 
< EKWEB_IN CLUD2 > 
ewaForinServe_* 
evaFoimSubmi t_* 

« « * 


The application resumes the request. 
The server re-invokes the application 
code attached to the requested docu- 
ment in order to constnjct a response 
on-the-fly. 




evaNeCBuff ezAl* 
loc 

ewaNctHTTPSend 
{STATUS_YIEUf) 


The server allocates and sends a 
response buffer. The application trans- 
mits the data and requests that the 
server yield the CPU. 


ewsRun 

■ * * 


ewaNecBuffezAl- 
loc 

ewaNetKTTPSend 
(STATUS_VIELD) 


The application reschedules the 
server. The server sends the next 
buffer. 


evsRun 


ewaNecBuf f ei Fiee 

m t m 

evaFxee . . . 
evaNetHTTPEnd 


The application reschedules the 
server. The server releases resources 
and terminates processing of the 
request. 


The next table illustrates a typical scenario in whicfi the application aborts processing of 
an incomplete HTTP request 


Application->Server 
(Abort) 


Server -> 
Application 


Description 


evsNetHTTPStait 


evaAlloc 

* 4 • 


Application accepts a new HTTP TCP 
connection request and informs the 
EmWeb/Server. The server allocates 
memory resources for the request. 


evsNe cKTTPRe ce i ve 


evaAlloc 

i « ■ 

evaNecBuff ezPzee 

* • * 


Application accepts request data from 
the network and passes it to the server 
for processing. The server may allo- 
cate memory resources to process the 
request as needed. Some network 
buffers received may be released at 
this point. 
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Appiication->Server 
(Abort) 


Server -> 
Application 


Description 


evsNetHTTPAboiC 


evaFiee 

mm* 

ewaNetBuf feiFiee 
evaNeCHTTPEnd 


Application requests abort of HTTP 
transaction in progress. Server 
releases resources and terminates 
request. 


The next table Illustrates the on-demand archive loading leature of EmWeb. 


AppiiCaiion'''ot;r vci 
(Demand Loading) 


Application 


Description 






Aonlieation reoisters a URL with 
EmWeb/Server that Is not loaded. 


ewsNeCHTTPStaiC 


ewaAlloc 


Application accepts a new HTTP TCP 
connection request and Informs the 
EmWeb/Server. The server allocates 
memory resources tor the request. 


ewsNetHTTPReceive 


eva Alloc 

• * < 

ewaNetBuf fezFiee 

• 4 • 


Application accepts request data from 
the network and passes It to the server 
for processing. The server may allo- 
cate memory resources to process the 
request as needed. Some network 
buffers received may be released at* 
this point. 




ewaDocutnentFaul t 


The server recognizes the requested 
URL to be a registered document and 
notifies the application. 


evsDocumencXnscallAx - 
chive 




The application loads the archive con- 
taining the document. 


ewsRun 


<emweb_strimg> 
<emweb3include> 
evaFoTDvSexve_" 
evaFoimSubmi t_* 
ewaCGl Starts" 
evaCCIDaCa_* 

* * * 


The server automatically continues 
processing the request once the docu- 
ment has been loaded. The sen/er 
invokes the application code attached 
to the requested document in order to 
construct a response on-the-fly. 




evaNecBuff ex Al- 
loc 

• ■ * 

evaNetHTTPSend 
(STATUS_OK) 

» • • 


The server allocates network buffers 
as needed, fills them with HTTP 
response data, and sends them to the 
application for transmission. 



CopyrigMQ 1997 Agranat Systems, Inc, Page 64 

SUBSTITUTE SHEET (RULE 26) 



REV. 6/20/97 



wo 98/06033 

EmWeb^^ Functional Specification 



-93 - 
Confidential 



PCT/US97/13817 



EmWeb/Server 



AppUcation-> Server 
(Demand Loading) 


Server -> 
Application 


Description 




ewa?iee 

< t a 

evaNetBuf feiFxee 

• ■ • ■ 

ewaNetHTTP£nd 


The server releases any remaining 
resources associated with the HTTP 
transaction and tenminates the 
request. The application closes the 
TCP connection at this point. 



4.3, Porting Guidelines 

The EmWeb/Sen/er is distributed as a directory tree of ANSI C files. In order to assure 
the best possible upgrade path and support Irom Agranat Systems, most of these files 
should not be modified by the system integrator. 

To port EmWeb/Serverto a specific target environment foo, atargel-speclfic conf ig. foo 
configuration directory must be aeated. config.foo contains the target-specific 
configuration files ev_ types .h, ev_con£ig .h, and conf ig .mak. These files can be copied 
from the examples provided in the config directory, and modified as appropriate for the 
target. 

To build the server library obj . f oo/evs .a, use the following command: 

make CONFIG-foo server 

Note: The configure script may be used on Unix systems to 
automatically generate the configuration files for the local Unix 
development environment target. Typing "make" will build the 
Em Web/Compiler, the example archives, and the reference 
Unix port. 

4.3.1. Configuration Header Files 

The sic/config/ev types . h file contains definitions for base C types used throughout 
the EmWeb/ServerT Most of these are straightforward and generally do not require 
modification under 32-blt CPU architectures. The one definition which may require 
modification by the system Integrator is the preprocessor symbol emweb^endian which 
is defined to either emweb_endian_eig or emweb_endiam_little, and reflects the byte- 
order of the target prowssor (Intel processors are generally little endian while 
Motorola processors are generally big endian). The symbol emweb_archive_ekdian 
Indicates the byte-order of the archive generated by the EmWeb/Compiler. By default, 
the compiler generates big-endian archives unless the -litcie command-line 
argument is present. Note that rt is more efficient if the byte-order of the archive 
matches the byte-order of the target processor. 

The sic/conf ig/ew_config.h file definitions are expected to be modified extensively 
lor porting Em Web/Server to a particular hardware platfomi as follows: 
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EW_CONFIG_HTTP_PROTOCOL 

Define the level of protocol confomiance desired, f^ust be set to either 

HTTP_1_0or HTTP.l.l. 

EW_CONFIG_OPTION_DATE 

Define to enable generation of HTTP Dace: headers. This function requires 
that the application provide the evaoate function. This is required for 
protocol conformance, but some environments may simply not be able to 
determine the time*of-day, 

EW_C0NFIG_0PT10N_EXPIRE 

Define to enable generation of HTTP Expire: headers. The symbol 
Ews_coNFiG_oPTioH__DATE must also be defined. If a dynamic document is 
requested (i.e. a document containing content defined by the application as 
it is being served), then an Expiie: header is generated with the current 
time. Otherwise, no Expire: header is generated. The code size may be 
reduced by not defining this symbol. This is recommended for proper HTTP 
caching. 

EW_CONFIG_OPTION_LAST,MpDlFIED 

Define to enable generation of HTTP Last -modified: headers. The symbol 
Ews_coNFiG_oPTioN_DATE must a! SO be defined. If a static document is 
requested, then the"archive aeation date Is returned to the Web browser. 
Otherwise, the current time is returned to the Web browser. The code size 
may be reduced by not defining this symbol. This is recommended for 
proper HTTP caching. 

EW_C0NFIG_0PT10N_C0NDITI0NAL_GET 

Define to enable parsing of received if -Modified-since: headers to 
support conditional get functionality defined in the standard. This is 
recommended for proper HTTP caching. 

EW_C0NFIG_0PT10N_PRAGMA_N0CACHE 

~ DefineTo enable generation of "pragma: no- cache" HTTP/1.0 headers for 
documents containing dynamic content. 

EW_CONFIG.OPTION„PERSISTENT 

" DefineTo enable persistent connections. This Is recommended, especially 
with HTTP/1.1, for optimum network performance. Persistent connections 
enable the browser to pipeline multiple HTTP requests over a single TCP/ 
IP connection which was not possible In the original HTTP/1 .0 specification. 

EW_C0NFiG_0PT10N_CHUNKED_0UT 

HTTP/1.1 only. Define to enable the generation of chunked encoded data 
during transmission of documents containing dynamic elements. This 
makes maintaining a persistent connection- possible under certain 
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Circumstances and is strongly recommended. 

EW„CONFIG_OP"nON_CHUNKEDJN 

HTTP/1.1 only. Required for protocol conformance. Define to enable 
parsing of chunked form data received from the browser. 

EW_CONFIG„OPTION_METHOD.OPTiONS 

Define to enable HTTP/1,1 options method. 

EW_CONFIG_OPTION_METHOD_TRACE 

Define to enable HTTP/1.1 trace method. 

EW.CONFlG_OPT10N_CACHE_CONTROL 

Define to enable generation of HTTP/1.1 Cache-Control: headers. 
Recommended for optimum cache control. 

EW„CONFIG_OPTION_STR1NG 

Define If the application intends to use the <emwi:b_string> feature. 
Otherwise, code size may be reduced by not defining this symbol. 

EW_CONFlG_OPTlON_STRING_TYPED 

Define to enable typed e«web_strings (i.e. use of emweb_type attribute), 

EW.CONFIG.OPTIONJNCLUDE 

Define if the application intends to use the <emweb_include> feature. 
Otherwise, code size may be reduced by not defining this symbol. 

EW_CONF1G_OPTION_FORM 

Define if the application intends to use the EmWeb form processing 
interfaces. Otherwise, code size may be reduced by not defining this 
symbol. 

EW_CONFIG_OPTIONJMAGEMAP 

Define if the application intends to use EmWeb imagemaps. Otherwise, 
code size may be reduced by not defining this symbol. 

EW_C0NFIG„OPTION_CGI 

Define If the application intends to use the raw CGI application interfaces. 
Othenftfise, code size may be reduced by not defining this symbol. 

EW_CONFIG_OPT10N_LINK 

Define If the application Intends to use the link attribute in _access files. 
Otherwise, code size may be reduced by not defining this symbol. 

EW^CONFIG.OPTION.CLONING 

Define if the application intends to use the evscocuwentcione application 
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interface. Otherwise, code size may be reduced by not defining this symbol. 

EW_CONFIG_OPTION_DEMAND.LOADING 

Define if the application intends to use the evsDocumenLRegistez/ 
evaDocumentFauic application Intertace. Otherwise, code size may be 
reduced by not defining this symbol. 

EW_CONFIG_OPTION_DOCUMENT_DATA 

Define if the application intends to use the ewsDocumentDaca application 
interface. Otherwise, code size may be reduced by not defining this symbol. 

EW.CONFIG^OPTION.DOCUMENT.SET.REALM 

Define if the application Intends to use the ewsDoeumencsecReaim application 
interface. Otherwise, code size may be reduced by not defining this symbol. 

EW_CONFIG„OPTION_CLEANUP 

Define if the application desires to perform a graceful shutdown of the 
Em Web/Server by invoking ewsshucdovn. In some application 
environments, graceful shutdown may not be necessary as a system restart 
may be accomplished by a re-boot of the processor. The code size may be 
reduced by not defining this symbol 

EW_C0NFlG_OPTlON_SCHED 

Define if the application intends to use EmWeb's internal scheduler making 
use of the ewsRun application interface. Otherwise, the code size may be 
reduced by not defining this symbol. 

EW_CONFIG_OPT10N_SCHED_SUSP_RES 

Define if the application intends to use the evssuspend/ewsKesume 
application interfaces. Otherwise, the code size may be reduced by not 
defining this symbol. 

EW_CONFlG_OPTION_SCHED_FC 

Define if the application intends to use the evsuetFiovcontroi/ 
un7iowconcroi application interfaces. Otherwise, the code size may be 
reduced by not defining this symbol. 

EW_CONFIG_OPTlON_URL_HO0K 

~ Define if the application Intends to use the URL rewriting feature by 
providing the function ewaunLHook interface. Otherwise, the code size may 
be reduced by not defining this symbol. 

EW_C0NFIG_0PT10N_AUTH 

Define to enable support for authentication through the evsAuthRegisrer 
application Interface. Otherwise, the code size may be reduced by not 
defining this symbol. 
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EW_CONFlG_OPTION„AUTH„BASlC 

Define to enable support for the HTTP/1.0 basic cookie authentication 
method. The symbol ew_config_option_auth must also be defined. The 
code size may be reduced by not defining this symbol. 

EW.CONF1G_OPTION.AUTH_MBASIC 

Define to enable support for the "manual basic" authentication scheme. The 
code size may be reduced by not defining this symbol. 

EW„CONFiG_OPTION_AUTH_DlGEST 

Define to enable support for the HTTP/1,1 digest authentication method. 
The symbol ew_config_option_auth must also be defined. The code size 
may be reduced by not defining this symbol. 

Note: EmWeb's digest authentication support is derived from 
the RSA Data Security, inc. MD5 Message-Digest Algorithm. 
The foliowing legal notice can be found in src/lib/ew_md5c.c: 

copyiight (C) 1991-2, RSA Data Security, Inc. created 1991. All 
rights reserved. 

License to copy and use this softvaie is granted provided that it 
is identified as the "RSA Data Security, Inc. KD5 Message-Digest 
Algorithm" in all maneiial mentioning or referencing this software 
01 this function. 

License is also granted to make and use derivative vorks provided 
chat such works are identified as "derived from the RSA Data 
Security, Inc. Message-Digest Algorithm" in all material 
mentioning ox referencing the derived work. 

RSA Data Security, Inc. makes no representations concerning either 
the merchantability of this software or the suitability of this 
software for any particular purpose. It is provided "as is" 
vicbout express or implied warranty of any kind. 

These notices must be retained in any copies of any part of this 
documentation and/or software. 

EW_CONRG_OPT10N_AUTH_MDIGEST 

Define to enable support for the "manual digest" authentication scheme. 
The code size may be reduced by not defining this symbol. 

EW„CONFIG_OPT10N_AUTH_DIGEST_M • 

Define to enable support tor the dlgestRequlred parameter used in digest 
authentication. This protects against forged messages using proper 
authentication credentials. The symbol ek_cohfig_option_auth_digzst 
must also be defined. The code size may be reduced by not defining this 
symbol. 



Copyrights 1997Agranat Systems, Inc. Page 69 

SUBSTITUTE SHEET (RULE 26) 



REV. 6/20/97 



>VO 98/06033 

EmWeb"'''^ Functional Specification 



-98- 
Confidenb'al 



PCT/US97/13817 



EmWeb/Server 



EW_CONFIG_OPHON_AUTH_VERIFY 

Define to enable support for secondary application-defined authentication. 
The code size may be reduced by not defining this symbol. 

EW C0NHG_0PTI0N_RELEASE_UNU5ED 

Define "to include extra code that attempts to release received network 
buffers as soon as possible if they do not contain infomiation needed forthe 
duration of an HTTP request. Otherwise, if HTTP headers are typically 
received in multiple network buffers, the EmWeb/Server may hold on to 
these buffers longer than necessary. 

EW.CONFIG_OPTION„FILE 

Define to include local file system support. The code size may be reduced 
by not defining this symbol 

EW„CONFIG_OPTION_FILE_GET 

" Define to include access to local filesystem for GET method requests. This 
option requires Ew_coNnG_otTioN_FiLE. The code size may be reduced by 
not defining this symbol. 

EW CONFIG_OPTION_COIV!PRESS 

Define to include extra code required for decompression of compressed 
archives. 

EW_CONF1G.OPT10N_CONTEXT_DATE 

DefineTo enable the ewscontextoate application interface. The code size 
may be reduced by not defining this symbol. 

EW C0NFIG_0PT10N_C0NTEXT_PRAGMA 

Define To enable the evscontextpiagma application interface. The code size 
may be reduced by not defining this symbol. 

EW_CONFlG.OPT10N_CONTEXT_FROr\/l 

Define To enable the ewsconcexcFrom application interface. The code size 
may be reduced by not defining this symbol. 

EW.CONFIG_OPTION_CONTEXTJF_MOD1F1ED_SINCE 

Define "to enable the ewscontextifModiJiedsince application interface. 
Furthermore, EmWeb/Server honors the HTTP if -modified -since: 
header for static documents by comparing to the archive creation date. 
(Note that dynamic documents are always served). The code size may be 
reduced by not defining this symbol. 

EW CONFIG OPTION_CONTEXT_REFERER 

Define To enable the ewsconcexcRefeiei application interface. Otherwise, 
the code size may be reduced by not defining this symbol. 
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EW_CONF!G_OPTION_CONTEXT_USER_AGENT 

Define to enable the evscontextuseiAgent application interface. Otherwise, 
the code size may be reduced by not defining this symbol. 

EW.CONFIG_OPTION_CONTEXT_HOST 

Define to enable the ewsContextHost application interface. Otherwise, the 
code size may be reduced by not defining this symbol. 

EW_CONFIG_OPTION_SEND.REPLY 

Define to enable the ewsContextSendReply application interface. 
Otherwise, the code size may be reduced by not defining this symbol. 

EW_CONFIG_OPTION_CGLSERVER_SOFTWARE 

Define to enable the ewscGi:;erversof cvare application interface. 
Otherwise, the code size may be reduced by not defining this symbol. 

EW_CONFJG_OPTION_CGI_GATEWAY„INTERFACE 

Define to enable the evscciGatevayinteiface application Interface. 
Otherwise, the code size may be reduced by not defining this symbol. 

EW_CONFIG_0PTI0N.CGLSERVER_PROTOC0L 

Define to enable the ewscciseiveipiotocoi application interface. 
Otherwise, the code size may be reduced by not defining this symbol. 

EW_CONFIG_OPT10N_CGLREQUEST_METHOD 

Define to enable the evscciRequcstMechod application interface. Otherwise, 
the code size may be reduced by not defining this symbol. 

EW_CONFIG.OPTION_CGLPATHJNFO 

Define to enable the evscoipathinf o application interface. Otherwise, the 
code size may be reduced by not defining this symbol. 

EW_CONFIG_OPT10N„C6l_SCRIPT_NAIME 

Define to enable the evscczsczipcName application Interface. Otherwise, the 
code size may be reduced by not defining this symbol, 

EW_CONFIG„OPTI0N.CGLQUERY.STRING 

Define to enable the evscciouerystring application interface. Otherwise, 
the code size may be reduced by not defining this symbol. 

EW_CONFIG_OPTION_CGI_CONTENT.TYPE 

Define to enable the ewsccicontencType application Interface. Otherwise, 
the code size may be reduced by not defining this symbol. 

EW_CDNFIG_OPTION_CGLCONTENT.LENGTH 

Define to enable the ewsccicontentLength application interface. Otherwise, 
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the code size may be reduced by not defining this symbol. 

EW_CONFlG_OPT10N.CGLCONrrENT_ENCODING 

Define to enable the evscciconcencEncoding application interface. 
Otherwise, the code size may be reduced by not defining this symbol, 

EW_CONFIG_OPTION_FIELDTYPE_RADIO 

Define to enable support for EmWeb HTML form radio buttons. Otherwise, 
the code size may be reduced by not defining this symbol. 

EW_C0NFIG_0PTI0N_F1ELDTYPE_SELECT_SINGLE 

" Define "to enable support for Em Web HTML form single option selection 
boxes. Otherwise, the code size may be reduced by not defining this 
symbol. 

EW_CQNFIG_OPTION_FIELDTYPE_SELECT_MULTIPLE 

" DefineTo enable support for EmWeb HTML form multiple option selection 
boxes. Otherwise, the code size may be reduced by not defining this 
symbol. 

EW_C0NFIG_0PT10N_F1ELDTYPE_CHECKB0X 

Define to enable support for EmWeb HTML form checkbox fields. 
Otherwise, the code size may be reduced by not defining this symbol. 

EW_CONFlG_OPTION_FIELDTYPE_TEXT 

Define to enable support for EmWeb HTML form text fields. Otherwise, the 
code size may be reduced by not defining this symbol. 

EW_C0NF1G_0PT10N_F1ELDTYPEJMAGE 

" Define to enable support for EmWeb HTML form image inputs. Otherwise, 
the code size may be reduced by not defining this symbol. 

EW_CONFIG_OPTION_FIELDTYPE_DECIIWAL_UINT 

DefineTo enable support for EmWeb HTML form text fields (or unsigned 
Integers. Otherwise, the code size may be reduced by not defining this 
symbol. 

EW C0NFIG_0PT10N_F1ELDTYPE_DECIMAL_INT 

Define lo enable support for EmWeb HTML form text fields for signed 
integers. Otherwise, the code size may be reduced by not defining this 
symbol. 

EW_CONFIG_OPTtON_FIELDTYPE_HEXJNT 

~ Define to enable support for EmWeb HTML form text fields for hexadecimal 
Integers. Otherwise, the code size may be reduced by not defining this 
symbol. 
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EW„CONFIG_OPT10N_FIELDTYPE_HEX„STRING 

Define to enable support for EmWeb HTML form text fields for hexadecimal 
octet strings. Otherwise, the code size may be reduced by not defining this 
symbol. 

EW_CONFIG_OPT10N_RELDTYPE.DOTTEDlP 

Define to enable support for EmWeb HTML form text fields for dotted IP 
addresses. Otherwise, the code size may be reduced by not defining this 
symbol. 

EW.C0NFIG_OPTI0N_FIELDTYPE_DECNETJV 

Define to enable support for EmWeb HTML fomn text fields for DECnet IV 
addresses. Otherwise, the code size may be reduced by not defining this 
symbol. 

EW_C0NFIG_0PT10N_FIELDTYPEJEEE_MAC 

Define to enable support for EmWeb HTML fomi text fields for !E£E MAC 
addresses. Otherwise, the code size may be reduced by not defining this 
symbol. 

EW_CONFiG_OPTION.FIELDTYPE.FDDLftflAC 

Define to enable support for EmWeb HTML form text fields for FDDI MAC 
addresses. Otherwise, the code size may be reduced by not defining this 
symbol. 

EW_CONFIG_OPTION_FlELDTYPE„STD_MAC 

Define to enable support for EmWeb HTML fonn text fields for big or little 
endian standard MAC addresses. Otherwise, the code size may be reduced 
by not defining this symbol. 

EW_C0NFIG_0PTI0N_FIELDTYPE„01D 

Define to enable support for EmWeb HTMLfomi text fields for SNMP object 
identifiers. Otherwise, the code size may b© reduced by not defining this 
symbol. 

EW_CONFIG_OPT10N_FlELDTYPE_FlLE 

Define to enable support for RFC 1 867 file upload from browser. This option 
requires Ew_coNFiG_opTioN_riLE. The code size may be reduced by not 
defining thirsymboL 

EW.CONFIG.OPTION_BROKENJMS.EXTRA_DATA 

Define to handle non-conformant browsers that place, extra data at the end 
of If-Modifled-Since: headers. Otherwise, the code size may be reduced by 
not defining this symbol. 
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EW_CONFIG_OPTION^BROKEN_NEED_OPAQUE 

Define to handle non-conformant browsers that require optional opaque 
field in digest authentication headers. Otherwise, the code size may be 
reduced by not defining this symbol. 

EwaNetBuffer 

Define the C type used to represent a buffer descriptor. 

EWA.NET_BUFFER_NULL 

Define the value of a null buffer descriptor used to temninate a chain of 
buffers or indicate no buffers available. 

EwaNetHandle 

Define the C type used for the application-defined network handle passed 
to EmWeb/Server in ewsNecHrrPstaic and available from the request 
context by ewsConCexCNeuHandle. 

EwaDocumentHandle 

Define the C type used for the application-defined document handle passed 

to EmWeb/Server In ewsDocumentClone or ewsDocumentRogiscer and 

available from the request context by ewsconcexcDocumentHandie. 

EWA_DOCUMENT_HANDLE_NULL 

Define the value for a null document handle stored in the context for 
documents that have not been cloned or registered. 

EwaAuthHandle 

Define the C type used for the application-defined authorization handle 
passed to EmWeb/Server In ewsAuchRegistei and available from the 

request context by ewsConcexLAuchHandle. 

EWS_AUTH_HANDLE.NULL 

Define the value for a null authorization handle stored in the context for 
requests that have not been authenticated. 

EwaAuthNonce 

Define the C structure containing parameters used in generating nonce 
challenges. 

EwaCGIHandle 

Define the C type used for the application-defined CGI handle passed to 
EmWeb/Server from ewacoiscait^* and returned to the application in 

subsequent ewaCGIData_*. 

EWA_CGLHANDLE_NULL 

"Define the value for a NULL CGI handle stored In the context for CGI 
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requests. 

EWA TASK_LOCK0 

This application-defined macro is invoked by EmWeb/Server to enter a 
critical region. If the application is preemptive and multiple threads may 
access EmWeb application interface functions simultaneously, then this 
macro should be defined In such a way as to disable preemption. 

EWA_TASK_UNLOCK0 

This application-defined macro is invoked by EmWeb/Server to leave a 

critical region entered by ewa_task_lock t) • 

EMWEB_ERROR0 

This application-defined macro is invoked by EmWeb/Server to report 
serious error conditions, usually a result of improper system integration. 

EMWEB^WARNO 

This application-defined macro is invoked by EmWeb/Server to report an 
error condition for which recovery is possible. 

EMWEB.TRACEO 

This application-defined macro is invoked by EmWeb/Server to trace 

execution for debugging, 

EWA.LOG.HOOK 

Define to enable the ewaLogwooko application Interface. Otherwise, the 
code size may be reduced by not defining this symbol. 

EMWEB.SANITY 

Define to enable extra code for checking the consistent use of the API and 
internal data stajctures. This is strongly recommended during initial porting 
and debug. However, the code size may be reduced by not defining this 
symbol. 

EMWEB.HAVE.MEMCPY 

Define to use application-provided run-time memcpy library function. 
Otherwise, extra server code Is included to Implement this functionality. 

EMWEe_HAVE_MEMSET 

Define to use application-provided run-time memset library function. 
Otherwise, extra server code is Included to implement this functionality. 

EMWEB_HAVE_SPRINTF 

Define to use application-provided run-time spiintf library function. 
Otherwise, extra server code Is included to handle conversions from 
integers to strings (%d. %x). 
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EMWEB_HAVE_STRCPY 

Define to use application-provided run-time sctcpy library function. 
Otherwise, extra server code is included to implement this functionality. 

EMVyEB.HAVE.STRLEN 

Define to use application-provided otn-time scrien library function. 
Otherwise, extra server code is included to implement this functionality. 

EMWEB_HAVE_STRCMP 

Define to use application-provided run-time scrcmp library function. 
Otherwise, extra sen/er code is included to implement this functionality. 

EwaFiieHandle 

Define the C type used for the application-defined file handle used in the 
local filesystem API. 

EWA„FILE_HANDLE_NULL 

Define the value for a kull file handle as used by the local filesystem API. 

EwaFileName 

Define the C structure used to represent an application-defined filename 
parameter as used by the local filesystem API. 

The following macros may be defined to ovenide EmWeb/Server defaults as follows: 

EWS_RLE_HASH_SIZE 

Default: 256. Infomnatlon about each unique URL loaded from an archive, 
registered, or cloned, is maintained in an open hash table for fast lookup. 
This macro may be defined to set the number of entries in the hash table, 
where each entry contains a pointer value. Smaller values will typically 
decrease memory usage while increasing search times. 

EWS_REALM_HASH_SI2£ 

Default: 4. Information about each unique realm defined in loaded archives 
or by the ewsDocumencsecReaino function Is maintained in an open hash 
table tor fast lookup. This macro may be defined to set the number of entries 
in the hash table, where each entry contains a pointer value. Smaller values 
will typically decrease memory usage while increasing search times. 

EWS_NONCE_QUEUE„SlZE 

~ Default: 4. If digest authentication is used, outstanding nonce values are 
maintained in a circular queue. This macro may be defined to set the 
maximum number of outstanding nonce values, where each value will 
contain approximately 48 bytes of state information plus the size of the 
application-defined EvaAuthwonce structure, l-arger values -are 
recommended If one-time nonces are to be used and/or many simultaneous 
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authenticated requests from different clients are likely. 

EWS_HTTP_STATUS_204, EWS_HTrP_STRING„204 

Default: "No Content", "\r\n". These macros may be used to override the 
status line and message body issued for a no content HTTP response, {This 
status is generated in response to a form submission application function 
returning NULL, or to an undefined region of an imagemap if no default URL 
was specified). 

EWS_HrrP_STATUS_304, EWS_HTTP_STRINC_304 

Default: "Not Modified", "\r\n". These macros may be used to ovenide the 
status line and message body issued for a not modified HTTP response. 
(This status is generated in response to a conditional GET request if the 
requested document has not changed since the "if-Modified-Since:" value). 

EWS_HTTP_STATUS_400, EWS_HTrP_STRING_400 

Default: "Bad Request", "\r\n400 Bad Request\r\n", These macros may be 
used to override the status line and message body issued for a bad request 
HTTP response. (This status is generated in response to an HTTP request 
that could not be parsed). • 

EWS_HTTP_STATUS„401 , EWS_HTTP_STRING_401 

Default: "Unauthorized", "\r\n401 Unauthori2ed\r\n". These macros may be 
used to override the status line and message body issued for an 
unauthorized HTTP response. (This status is generated in response lo an 
HTTP request that did not contain proper credentials to access the server). 

EWS_HTTP_STATUS_404, EWS_HrrP.STRING,404 

Default; "Not Found", "\r\n404 Not Found\r\n". These macros may be used 
to override the status line and message body issued for a not found HTTP 
response. (This status is generated in response to an HTTP requests for an 
unknown or hidden URL). 

EWS_HTTP_STATUS_41 1 , EWS_HTrP_STRING_41 1 

Default: "Length Required", "\r\n41 1 Length Required\r\n\ These macros 
may be used to ovenide the status line and message body issued for an 
internal error HTTP response, (This status is generated In response to an 
HTTP/1 .1 request containing chunk encoded form data with 
Ew__coNPic^opTioN_cHtJNKEp_iN disabled). 

EWS_HTTP_STATUS_500, EWS_HTTP^STRING_500 

DefauFt: "IntemaTEn'or', "\r\n500 Internal ErrorWi". These macros may be 
used to ovenide the status line and message body issued for an internal 
en-or HTTP response. (This status is generated in response to an HTTP 
request resulting in a detectable internal en-or. This should not ever occur.) 
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EWS_HTrP_STATUS_501 , EWS_HTTP.STRING_501 

Default: "Not Implemented", "\r\n501 Not lmplemented\r\n". These macros 
may be used to override the status line and message body issued for a not 
implemented HTTP response. (This status is generated in response to an 
HTTP request containing a method not supported by the URL). 

EWS_HTTP_STAtUS_503, EWS_HTTP_STR1NG_503 

Default: "Service Unavailable", 'V\n503 SeTvice Unavailable\^^n". These 
macros may be used to override the status line and message body issued 
for a service unavailable HTTP response. (This status is generated in 
response to an HTTP request for a registered and unloaded document 
when the. application-specific ewaDocumentFauItQ function aborts the 
request rather than loading the archive containing the URL). 

4.3.2. Application-Provided Functions 

The following functions must be provided by the application: 

- System functions 

, ewaAIloc 
. ewaFree 

- Network functions 

. ewaNetBufferAlloc 
. ewaNetBufferFree 
. ewaNetBufferNextGet 
. ewaNetButferNextSet 
, ewaNetBufferLengthGet 
. ewaNetSufferLengthSet 
. ewaNetSufferDataGet 
. ewaNetBufferDataSet 
. ewaNetHTTPSend 
. ewaNetHTTPEnd 
. ewaNetHTTPCIeanup 
. ewaNetLocalHostName 



The foilovrtng functions may be provided by the application if certain optional Em Web/ 
Server features are desired. 

- System functions 

. ewaOate 
. ewaLogHool< 
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- Document Junctions 

. ewaDocumentFauIt 
. ewaURLHook 

- Authenlicaiion functions 

. ewaAuthRealmQuaiifier 

- Digest Authentication functions 

. ewaAuthNonceCreate 
. ewaAuth Nonce Check 

- Manual Authentication functions 

. ewaAuthCheckBasic 
, ewaAuth CheckDig est 
. ewaAuthVerifySecurity 

4.4. Memory Requirements 

The following table illustrates the approximate incremental executable image size of the 
EmWeb/Server for various configuration options enabled compiled using GNU gcc- 
2.7.0 with -02 for the Intel 486, the Intel i960, and the Motorola MC5BOO0 architectures. 
These values are subject to change without notice. 



Incremental Option 


1486 


1960 


MC68000 


Base EmWeb/Server functionality 


7,380 


7.496 


6.238 


<EMWEB_STR1NG> 


180 


216 


184 


Typed <EMWEB„STRING>s 


464 


464 


454 


<EMWEBJNCLUDE> 
(requires some additional code 
from <EMWEB^STBING>), 


384 


400 


312 


Base EmWeb HTML form support 


3,124 


3.168 


2.548 


imagemap support 


288 


320 


272 


Base raw CGI support 


640 


656 


578 


URL Link support 


16 


32 


28 


Document cloning 


400 


.400 


314 


Document on-demand loading 


492 


520 


440 
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Incremental Option 


1486 


i960 


MC88000 




OA 

t>*+ 


/ c 




Craeeful ^ejvpf shutdown 




9fi4 










AAA 


Proxy (ewsSuspend/ewsResume) 

fr^rt! lir^^ re>nf i^^t ^r'hoHtiUnn) 


320 


296 


242 


INCLWUIn IIUW UUdUUl 

(requires request scheduling) 


ODO 






URL rewriting (ewaURl-Hook) 


304 


208 


164 


Base filesystem support 


176 


224 


170 


GFT/HEAD from loca.1 filesvstem 
(Requires base filesystem sup.) 


1 87S 


1 4S0 




Base authenticatian suDDort 


1 16B 


1 032 


934 


Basic authentication 


952 


1.056 


824 


Digest authentication 


5.547 


6.732 


5,366 


Ciient message digest verification 
(requires digest authenttcatior)) 


1,335 


1,016 


742 


Manual basic authentication 
(requires basic authentication) 


608 


472 


482 


Manual basic decode 
(requires manual basic) 


336 


352 


198 


Manual digest authentication 
(requires digest authentication) 


384 


368 


366 


Manual authentication verification 


144 


144 


128 


Run-time document realm override 


0 


0 


0 


Base HTTP/1,1 support 


1,284 


1,160 


972 


Persistent connections 


883 


616 


614 


Generate chunked encoding 
(requires HTTP/1.1) 


828 


784 


632 


Parse chunked encoding 
(requires HTTP/1.1). 


855 


552 


468 


OPTIONS method 


250 


240 


192 
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Incremental Option 


i486 


I960 


MC68000 


TRACE method 


288 


268 


204 


Generate Cache-Control headers 


122 


128 


96 


Generate Date headers (ewaDate) 


41 


64 


32 


Generate Expire headers 
(ewaDate) 


76 


176 


60 


Generate Last-Modified headers 


82 


112 


76 


Conditional get support 


239 


280 


248 


Generate Pragma headers 


35 


48 


34 


Eariy release of network buffers 


224 


240 


208 


Compression 


525 


584 


462 


Parse Date headers 


64 


56 


72 


Parse Pragma headers 


75 


64 


82 


Parse From headers 


73 


72 


62 


Parse If-Modified-Since headers 


64 


64 


72 


Parse Referer headers 


76 


64 


86 


Parse User-Agent headers 


79 


104 


90 


Parse Host headers 


169 


128 


124 


ewsContextSendReply 


626 


632 


494 


ewsCGIServerSoftware 


31 


40 


30 


ewsCGIGatewaylnterlace 


24 


32 


22 


e ws CG 1 S e rve rProt oco 1 


64 


56 


66 


ewsCGlRequestMethod 


64 


64 


68 


ewsCGIPathlnfo 


16 


15 


16 


ewsCGIScriptName 


16 


16 


16 


ewsCGIQueryString 


.64 


64 


68 


ews CG IContentType 


80 


64 


72 


ewsCGIContentLength 


16 


16 


16 


ewsCGIContentEncoding 


64 


64 


72 
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Incremental Option 


i4S6 


I960 


MC68000 


Form radio buttons 


328 


304 


254 


Form single option select boxes 


57 


64 


62 


Form multiple option select boxes 


128 


144 


124 


Form checkboxes 


96 


96 


92 


Form text fields 


307 


352 


256 


rorm image inpui iieius 








Form text fields - unsigned integer 


0 


0 


0 


Form text fields - signed integer 
(requires some code from 
unsigned integer) 


98 


128 


90 


Form text fields - hexadecimal Int . 
(requires some code from 
unsigned Integer) 


154 


164 


166 


Form text fields - hex string 
(requires some code from 


706 


704 


550 


Form text fields - dotted IP 
(requires some code from 


354 


416 


310 


Form text fields - DECNet iV 
(requires some code from 
unstgneo inwgerj 


272 


352 


280 


Pnrm t^vt fiplHc • IFFf MAC 


144 


160 


136 


Form text fields - FDDI MAC 
fr^auirss some code from IEEE 
MAC) 


48 


48 


44 


Form text fields • Standard MAC 
(requires some code from lEBB 
MAC) 


160 


192 


168 


Form text fields - SNMP Object ID 


■400 


400 


340 


Fomn file filed s - file upload 
(requires base filesystem support) 


4,372 


4,232 


3,394 


1 Broken If-Modified-Since Extra 


84 


128 


124 
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Incremental Ootion 


IHOO 


1960 


MC68000 




16 


16 


16 


Kucifiai spriDu iioisuy 


656 


736 


582 




112 


336 


46 


iDiemai sircrTip iJDr&ry 


128 


184 


52 


iiiiciiicii All Id 1 (lurBiy 


-160 


384 


162 


IntpmpI rnpmf*pi\/ lihror\/ 
iiitciiioi iiiciiiLipy iiuidiy 


160 


80 


-8 


Internal memset library 


16 


1 ft 


-2 


Extra sanity checking code 


1,24B 


1.080 


1,008 


En*or reporting 


2,498 


2,984 


2,358 


Warning reporting 


2.527 


2,888 


2,350 


Debug tracing 


1,685 


2.392 


1.764 


Logging hook 


704 


1,056 


778 


FULL CONFJGURATION 


52,677 


55,34S 


44,740 



Note that some of the configurable options listed in the table above depend on pieces 
of code included from previous options as indicated. The table shows the incremental 
requirements as each option is added from top to bonom. Therefore, the executable 
image size for an arbitrary set of options may be different than the sum of the values 
shown above. 

Additional archive memory requirements Include 

- Compressed file contents and embedded application object code (controlled bv 
application) ' 

- 120 bytes per archive 

- 36 bytes per document in archive (plus nuli-temninated URL string) 

- 12 bytes per <emkeb_striijg> , <emweb_include> . CG! script, or form field 

- null tenninated strings for authorization realms, mime types, creation date. etc. 
• compression dictionary (if compression used). 

Additional run-time memory requirements include: 
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- Network buffers (controlled by application). EmWeb/Server typically holds on to 
received buffers containing HTTP headers of Interest for the duration of a request, 
and typically allocates only one or two buffers before sending them to the application 
for transmission. 

- 1,028 - 1,096 bytes total global EmWeb state (using defaults for hash table sizes 
which may be ovenidden by application) 

- 176 - 636 bytes per HTTP request (plus 48-52 bytes for ffrst served document, plus 
48 bytes for decompression context if compressed) 

- 48-52 bytes per nested <emweb_ihclude> document (plus 48 bytes for de- 
compression context If compressed) 

- 40-64 bytes per URL in archive (including clones and registered documents) 

- 20-44 bytes per authorization realm plus null-terminated realm name string 

- 20-28 bytes per authorization entry plus Base64 or MD5 encoding of user/password 
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5. Conformance 

The EmWeb/Server impiements the HTTP/1.1 and HTTP/1.0 protocois, and MD5 Digest 
Authentication. 

The EmWeb/Server raw CGI capabilities support the functionality of CGI/1,1, but the 
Interfaces are non-standard as they are optimized for the EmWeb/Server environment, in 
addition, some CGl/1.1 interfaces depend upon the specific integration of EmWeb/Sen/er 
into the application environment 

The EmWeb/Compiler supports HTML72.0 Fomis with RFC 1867 file upload extensions. 
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6. Release History 



Release 1.0(12/23/96) 


General Availability 


Release 1.1 (0^16/97) 


Added network flow-control interfaces 


Release 1 .2 (02/26/97) 


Ported Id VxWnrif <t 


Release 1.3 {^zmi^l) 


Ported to pSOS 


Release 2.0 (04/14/97) 


Added HTTP/1.1 support 
Added support for typed EMWEB STRINGS 
Added EMWEB.STATIC cache-control override 
Added support for remote authenticaUon databases' 


Release 2.1 (06/20/97) 


Added native fiiesystem support 
Added RFC 1857 (file upload from browser) support 
Added support for EMWEB_TrPE«OBJECT ID 
Added support for SNMP Research <mibob]> tags 
Added ewaNetHTTPCieanupQ interlaces 
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A. EmWeb Application Interface Header Files 



This appendix is intended for reference only and is not part of this specification. The C 
header files listed here are part of the standard EmWeb source distribution and may be 
updated from time to time. 



A-1. Configuration 

These sample configuration header files are provided in the EmWeb source distribution. It 
is expected that these files will be modified by the system integrator in order to port the 
EmWeb/Server to the target environment. No other files in the EmWeb distribution should 
be modified In any way. 



A-1.1. src/config/ew_types.h 

This files contains definitions for base C types used throughout the EmWeb product. In 
most environments, this file will not need to be modified except possibly for the definition 
of EMwsB_ENDiAN and EMW2B_ARCHivE_ENDiAN. However, for some compilers, it may be 
necessary for the system integrator to modify additional definitions here. 



• ew_cypcs.h,V 1.20 1997/03/31 19:14:25 lawrence Exp 

* Product: EmWeb 

* Release: R2_l 

* CONFIDENTIAL AND PROPRIETARY INFORMATION OF AGRANAT SYSTEMS, INC. 

* THE EMWEB SOFTWARE ARCHITECTURE IS PATENT PENDING. 

• EMWEB IS A TRADEM?J1K OF AGRANAT SYSTEMS, INC. 

♦ Copyiigtit (C) 1996, 1997 Agranat Systems, Inc. 

• All Rights Reserved 

* Agianac systems. Inc. 

* 134S Main Street 

• Waltham, MA 02154 

♦ (617) 893-7868 

* salesoagranat . com, supportSagranat . com 

• http://wvrw.agranat.com/ 

• EmWeb common types 
•/ 

ftiCndef _ew_types_h 
ttdefine EW~TyPES~H 



/• 
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* c-rypEs 

• The following basic C- types are defined (see ev config.h) 
#ifndef INT8 

# define INT8 signed char 
«endif 

#i£ndef UINT8 

*f define UIHTe unsigned chai 
ftendif 

Kifndef IKT16 

# define INTie short inc 
«endlf 

#i£ndef INT32 

# define INT32 long int 
Sendif 



ftifndef P_INT 

# define P^INT in' 

ffendif " 



/• on integer the same size as a point 



.er */ 



typedef INT8 intB; 

cypedef INT16 intis; 

typedef INT32 inc32; 

typedef mure uints; 

typedef unsigned INT16 uintl6; 

typedef unsigned 1HT32 uint32; 



/* signed eight bit integer */ 
/" signed sixteen bit integer •/ 
/• signed thirtytvo bit integer •/ 
/• unsigned eight bit integer -/ 
/• unsigned sixteen bit integer */ 
/• unsigned thirty -tvo bit integer •/ 



Volatiles fox memory shared vich devices 



typedef volatile ints vintB;. 
typedef volatile inti6 vintl6; 
cypedef volatile int32 vint32; 
typedef volatile uintB vuints; 
typedef volatile uintie vuinci6; 
typedef volatile uint32 vuint32; 



/• volatile signed eight bits •/ 

/' volatile signed sixteen bits */ 

/• volatile signed thirty -two bits 

/* volatile signed eight bits •/ 

/• volatile unsigned sixteen bits •/ 

/• volatile unsigned thirty -two bits */ 



/ 



* FAST TYPES 

* The following types offer the most efficient compilation for optimized speed 
*• These are never assumed to be more than 16 bits. 



typedef int 
typedef unsigned 



sintf ; 
uintf ; 



/* signed integer */ 
/* unsigned integer */ 



BOOLEAN 

The boolean type is used primarily as a function return type. Note that 
a default representation of TRUE and FALSE axe defined. However, care 
should be taken to avoid coinparing against these values. For most compilers 
TRUE can be any non-zero integer while FALSE is defined as zero. ' 
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*fdefine TRUE • {0 0) 

fidefine FALSE (ITRUE) 

cypedef uintf boolean; /• true or false (non-zero oi zero) •/ 

/* ^ 

• POIUTER INTEGER 

♦ The pointer integer is an unsigned integer large enough to accommodate a 

♦ machine pointer. This is used primarily for generic pointer arithmetic. 
V 

cypedef P_INT pint; /• unsigned integer for pointer •/ 

/• 

* NULL POINTER 
#ifndef NULL 

#define HULL (0) 
Kendif /• NULL ♦/ 

/* 

* ENDIAN {don't change these) 
*/ 

^define EMWEB_ENI3IAN_BIC 1234 
« define EMWEB ENDIAn"lITTLE 4321 

typedef enum Zndian_e 
{ 

ewBigEndian - EMWEB_ENDIAN_BIG , 
ewLitcleEndian ■ EKWEB_ENDIAN~LITTLE 
1 Indian; 

<tif D 
/• 

• EMWEB_EKDIAH - Define as endian-ness of target architecture 
•/ 

(fifndef EKWEB_ENDIAN 

# ifdef HAVE~CONFIG_H 
» include "config.h" 

U ifdef WORDS_B2GEKDIAN 

« define EMWEB^EKDIAN EMWEB_ENDIAN_BIC 

else 

9 define EKWEB_E1IDIAN •EMWEB_ENDIAK_LITTLE 

# endif 

# else 

# prag[na error -Define EKMEB_ENDIAN for target" 
« endif 

#else 

# pragma error "Define £MWEB_^ENDIAN for target" 
« endif /* HAVE_COHFIG_H •/ ~ 

fteadif /* :tbd; */ 

/• 

• EMWEB ARCHIVE ENDIAN 
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• Define endian for target archive as generated fay EtnWeb/Compilei 
♦/ 

^define EMWEB_ARCHIVE_ENDIAN EMWEB_ENIHAN_BIG 

• COMPILER COMPATIBILITY 

• B'EGl}i_BECtS precedes external definitions, END__DECLS follows external 

• definitions. These could be defined as 'extern "C" {' and respectively 
s * for GV\J C+* compilers, for example. 

#ifdef cplusplus 

«define ^BEGIN_DECLS extein "C- { 

# define END_DECLS ) 

<felse /• cplusplus */ 

ftdefine BECIN_i>ECLS 

fldefine END_DECLS 

ftendif /• cplusplus */ 

/• 

• PROTOTVPES 
•/ 

_BEGIN_DECLS 
END LECLS 



Vendif /• _EW_TYPE£_H */ 

A»1.2. src/config/ew_config.h 

This file must be modified by the system integrator to taylor EmWeb/Seiver to the target 
environment, 

/• 

• ev_confi9.h,V 1.77.2.3 1997/06/15 19:22:31 ian Exp 

• Product: EmWeb 

• Release: R2_l 

• CONriDENTIAL AND PROPRIETARY IHFORMATION OF AGRANAT SYSTEMS, INC. 

• THE EMWEB SOFTWARE ARCHITECTURE IS PATENT PENDING, 

• EMWEB IS A TRADEMARK OF AGRANAT SYSTEMS, INC. 

• Copyright (C) 1996, 1997 Agianat Systems, Inc. 

• All Rights Reserved 

• Agranat Systems, Inc. 

• 1345 Main Street 

« Waltham, MA 02154 

• (617) B93-786B 

• saleseagiana t . com , suppoi t®a gr ana t . com 
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* hccp: //vn^v. agranat.com/ 

* EmWeb cotninon conf iguzacion 
* 

«ifndef _EW_^CONFIQ_H 
#define 2ew_C0NFIG_H 

/• 

* Types for sized integers: INT8 INT16 INT32 Fjirrr 

* These are guesses as to the correct types to produce the 

* required sizes for your system. 

* The configure script will attempt to sec these correctly 

* for the compiler platform; you should set when you copy this 

* file for each target. 
V 

Jtifndef INTB 

# define INTQ signed chax 
t^endi f 



tfifndef INT16 

U define INT16 short int 
irendif 



ffifndef INT32 

# define INT32 int 

ffendif 



ffifndef P_INT /' an integer the same size as a pointer •/ 

» define P_INT int 

ffendif 

^include "ew_types .h" 
/* 

• INCLUDES 

• Any system includes needed by application environment go here 
*/ 

extern void application_tick() ; 
#include <stdio.h> 
tinclude <stdlib.h> 
# include < sys/ types. h> 
^include <netinet/in.h> 
^include <signa 1 . h> 

/• 

• HTTP PROTOCOL VERSION 
'/ 

ft define HTTP_1_0 1000 /« DO NOT MODIFY •/ 

tt define HTTP 1~1 1001 /-DO NOT MODIFY •/ 

/• 

• Select desired conformance level 
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#define EW_CONnG_HTTP__PR0TOCOL HTTP_1 1 



PROTOCOL OPTIONS (>- HTTP/1.0) 

(R> Required, but some embedded systems don't have time-of-day 



• (O) Optional, but strongly recommended 

Odefine EW_C0NPIC_OPnON_I>ATE /• (r) 

#define EW_COMriG~OPTION"EXPIRE /• (o) 

# define EW_C0KFIG_OPTI0N_LAST_MODinED /• (0) 

#define EW_CONnG"opTION_CONDITIONAL GET/" (O) 

^define EW_COHFIC~OPTION_PRAGMA_HOCACHE /* (O) 



Generate Date: */ 
Generate Expiiei */ 
Generate Last-modified: •/ 
Parse If -Modified-since: •/ 
Generate Pragma! no -cache •/ 



PROTOCOL OPTIONS (>- KTTP/l.l) 

(O) Optional, but strongly recommended 
(•> May be used vith HTTP/i.o 



•/ 

^define EW_C0NriC_0PTION__PERSI STENT /^ 

^define EW_C0HriC_OPTI0N2cHUNKED_0UT- /" 

^define EW_COHriG__OPTION_CHUHKED_IN /" 

^define ew_confic_option2method_options /* 

Kdefine EW~CONriG~OPnON~METHOD"TRACE /* 

#undef EW^CONFIG_OPTION_METHOD__PUT /• 

ffundef EW_CONFIG_0PTION~METH0D~DELETE /• 

^define EW_CONFIG OPTION CACHE"cONTR0L /• 



tO») persistent connections */ 
(O) respond with chunked encoding 
(OJ parse chunked encoding •/ 
(O*) support OPTIONS method */ 
(O*) support TRACE method •/ 
{") support PUT operations */ 
{*) support DELETE operations •/ 
(0*) Generate Cache-Control: »/ 



'/ 



CONFIGURATION OPTIONS 



The EirtWeb/Server may be customized by the application developer to balance 
between functionality v.s. memory and CPU requirements. Each of the options 
below may be selected (fldefine) or unselected (ffundef) . 



e[nweb_string support •/ 
typed emweb_string support •/ 
emweb^include support •/ 
form support */ 
support for imagemaps */ 
raw CGI support •/ 
link node support */ 
URL cloning support •/ 
demand document loading support */ 



•/ 

^define EW_COHFIC_OPTION_STRING /' 

** define EW_CONFIG_OPTION_STRING_TYP£D /' 

^define EW_C0NFIC~0PTI0n2iKCLUDE /' 

*»define Ew'conFIg'oPTION^FORM /' 

^define ew'configI^option'ikagemap /- 

^define EW~CONFIg2oPTION_CGI 

#define EvTcONFIc'cPnON^LINK /* 

«define EW_CONFIG_OPTION~CL0NING /• 

•define EW~C0NFIG_OPTION~DEMAND__L0ADING /• 

♦define EW_CONFIG~OPTIONJ30CUMENT_DATA /• 

tfdefine EW_C0NFIGj,0PTI0n"D0C0MENT~SET__REALM /* run -time realm a 

•define EW_cONFIG_OPTION_CLEANUP /• 

ftdefine EvrcoNFIG_OPTION_SCHED /* 

♦define EW~CONFIG_OPTION__SCHED_SUSP_RES /* 

♦define EW~CONPIG_OPTION~SCHnrrC ~ /• 

♦define Ew2cONFIG_0PnON_ORL__H0OK /* 

♦define EW_C0NFIG~OPTI0n3aX3TH /* 

♦define ew~config~option"auth_basic /♦ 

♦define EW_CONFIG_OPTION~AUTH_DIGEST /• 

♦define Ew"cONFIG~OPTION AUTH^DIGEST M /* 



direct archive data access support •/ 

ssignment sup. */ 
graceful cleanup support */ 
request scheduling support •/ 
suspend/resume request support •/ 
flow control support •/ 
request URL rewriting hook */ 
authorization support •/ 
basic authorization support •/ 
digest authorization support «/ 
verify client message digest •/ 



Copyright 0 1997Agranat Systems, inc. Page 93 

SUBSTITUTE SHEET (RULE 26) 



REV. S/20/97 



wo 98/06033 



PCT/US97/13817 



122 

EmWebTM Functional Specification clnndentiat src/confi8/ew_config. h 

E"_CONFIG_OPTION_AUTH_MBASIC -manual" basic authencicacion V 

^define EW_C0NFIG_0PTION_AUTH_MBASIC_DECODE /* do base64 decode for MBASIC •/ 
#define EW_CONFIG_OI>nON_AUTH_MDIGEST /• "manual" digest authentication V 
#define EW_cONriG_0PTION_AUTH_VERinf /• manual verification of client •/ 
ttdefine EW_CONFlG„OPTION_COMPRESS archive decompression support V 

Jdefine EW_C0NFrG_0PTlON_RELEASE.UNUSED Eatly release of unused buyers V 
^define EW„CONPIG_OPnON_FrLE /. local filesystem support V 

Jdefine EW_CONFIG,OPTION_FILE_GET /• local filesystem GET method V 

#define EW_C0NriG_0PTION_FILE_DELETE /* local filesystem DELETE method V 
#define EW_cONFIC_omON.riLE_PUT /* local filesystem PUT method V 

/* 

• Options to include support for retrieving HTTP request headers 

Ifdefine EW_C0NFIG_0PTI0N__C0NTEXT_DATE 

ftdefine EW_CONPIG~OPTION~C0NTEXT_PRASMA 

#define EW_CONFIG_0PTIOH_C0NTEXT_FR0M 

#de£ine EW_C0NFIG_0PTION_C0KTEXT_IF_MODIFIED_SINCE 

«define EW_CONFIG_OPTIOK_CONTEXT~ilEF£RER 

ttdefine ew_cohfig_option_context"user^acent 

^define EW^CONFIG^OPTTON^CONTEXt'hOSt" 
/• 

• Option for serving document to browser in response to form or CGI 

* / 

#def ine EW_C0NFIG__OPTION_C0KTEXT_SEND_REPLy 
/* 

* Options to include support for CGI access functions 
•/ 

sdefine ew_config_option_cgi_server_software 

*t de f i ne E W^CONFI G_0 PTI 0N_CGI~CATEWAY_INTERFACE 
ttdefine EW_CONFlG_OPTION~CGI_SERVER PROTOCOL 
(tdefine EW_CONFIG_OPTION_CGIJtE0UEST METHOD 

ttdefine ew_config~option_cgi_path__info 
ttdefine ew_config~option_cgi~script_name 

ttdefine EW_CONriG~OPnON_CGI~OUERY_STRIHG 
tt de f i ne EW_CONFI G~0 PT10N~CGi2cONTENT_TYPE 
ttde f i ne EW_CONFI G_0PTI ON~CGl"cOin'EKT_LENGTH 
ttdefine EW_C0NriG_OPTION~CGI~C0NTENT~ENC0DING 

/* 

* Options to handle certain form field types (EW CONFIG OPTION FORM must be 

• defined for these to take effect) . - - - 
•/ 

ttdefine EM_CONriG_OPTION_FIELDTyPE_RADIO 
ttdefine EVrC0NFIG~0PTION~FIEU>TVPE2s ELECT SINGLE 
ttdefine EW_C0NFIG~0PTI0N~riEIJ>TYPE2sELECT~MULTIPLE 

ttdefine ew_config~option"fieldtvpe"checkbox 

ttdefine EW_C0NFIG~0PTION_FIELDTYPE_TEXT 
ttdefine EW_C0NFIG_0PTION~FrELDTypE~lMAGE 
ttdefine EW_CONFIG~OPnON3FIELDTyPE_DECIMAL_UINT 
ttdefine EW_CONriG_OPnON"FIELDTypE~DECIMAL_INT 
ttdefine EW^CONFIG OPTION fieldtype~hex int" 
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*fde£ine EW_CONFIG_OPTIOK_FIELDTVPE_HEX_STRING 
ftdefine EW_CONFIG__OPTION_FIELDTYPe"dOTTEDIP 
^define EW_C0KFIG^0PTI0N_riELDTypE2DECNET_IV 
^define EW_CX)NFIg"oPTION~FIELDTVPE_IEEE_MAC 
Kdefine EW_CONFIG"oPTION3FIELDTyPE2FDDl2MAC 
ftdefine EW__CONFIG3oPTION~FIELDTyPE_STD_MAC 
#define Ew"cOJIFIG_OPTION~FIELDTYPE_OID 
^define EW_CONFIG_0PTI0N^FIELDTyPE"FILE 

/* 

* Foice use of the buffer early release option if support for 

* file input field • needed so ve don't buffet the entire 

* incoming file. 
•/ 

ififdef EW_CONFIG_OPTION_FIELDTYPE_FILE 
ttifndef EW_CONFIG~OPTION*RELEASE_Um;S£D 
^define EW_C0NnG_OPTION"RELEASE_UNUSED 
#endif /• EW_CONFIG_OPTION_RELEAiE_UNUSED •/ 
♦tendif /• EW_CONFIG~OPTI0N~FIELDTyPE_FILE •/ 

/' 

* Options to handle non- conformant browsers 

* BROKEN__IMS_EXTRA_DATA • Several recent versions of Netscape incorrectly 

* add extra infoimation ac the end of an If -Modified -Since; header in the 

* form {size • n) " . This is in violation of the HTTP specification and 

* causes EmWeb/Server to effectively ignore the header. Since so many 

* browsers exhibit this behaviour, this work -around is provided to ignore 

* extra characters after the date string. 
•/ 

«def ine EW^CONFI G_OPTI ON_BROKEN_IMS_EXTRA_DATA 

/* 
• 

* BROKEN_NEED_OPA0UE • NCSA_Mosaic/2 . 7b5 and Spyglass_Mosaic/2 . 11 

* incoiiectly require the server to generate an opaque parameter 

* in WWW- Authenticate: headers using Digest authentication. 

*t d e f i ne EW_CONri G_OPTI ON_BROKEN_NEED_OPA0UE 
/* 

* SANITY CHECKING 
• 

* Define EMWEB^SANITY to include extra sanity chec)sing code during initial 

* integration and debugging. Code size may be reduced by not defining this. 

#define EHWEB_SAliITy 
/* 

* PORT -SPECIFIC DEFINITIONS 
*/ 

^define evaAlloc inalloc 
ltdefine ewaFree free 
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• TRACIKG AND LOGGING 

• The following maczos provide tracing and logging facilicies using ANSI 

• princfO style argumencs. 



#define EKWEB_ERROR(x) 
ffde£ine EKWEB~WAKN(x} 
#de£ine EMWEB~TRACE (x) 
#define ewa LOG HOOK 



princf X 
printf X 
/•printf X*/ 

/• define to include ewaLogHookO interface */ 



NETWORK BUFFERS 

The netvozk buffer structure is defined by the application and used 
by the EmWeb/Server . A network buffer could be an index into an array, 
a pointer to a buffer descriptor, etc. EmWeb/Server imposes only the 
following requirements on the application's buffer implementation: 

o Given a buffer, a pointer to the start of data may be determined, 
o Given a buffer, the number of bytes of data may be determined or 

specified. The EmWeb /Server will never attempt to increase the 

size of a buffer . 
o Given a buffer, the next buffer on a singly linked list may be 

determined or specified. 

The EwaNetBuffer structure is used by EmWeb/Server to represents a buffer 
descriptor. The value EWA_NET__BUFFER_NULL indicates a NULL buffer used to 
terminate a buffer chain or as a return value from EwaNetBuffezAllocO 
indicating no buffers available. 



typedef struct EwaNetBuf fer_s 



t 



struct EwaNetBuf {er_s 

uinc6 

uinte 

uintf 



* next; 

* realdata; 

* data; 
length; 



} EwaNetBuf fer_t, • EwaNetBuff er ; 
«define EWA_NET_BUFFER_NULL ( (EwaNetBuf fez) NULL) 

/* Buffer primitives - these may be macros or subroutines •/ 



#define ewaNetBufferLengthGet (buffer) 
ltdefine ewaNetBuff ezLengthSet tbuf f ei , len) 
#def ine ewaNetBufferDacaGet (buffer) 
Sdefine ewaNetBuf f erDataSet (buf f ez , dacap) 
«def ine ewaNetBuff ezNextGet (buffer ) 
#define ewaNetBuff erNextset (buffer , nxt) 



(buffer) 
(buffer) 
(buffer) 
(buffer) 
(buffer) 
(buffer) 



*> length 
- > length 
• >data 
•>data " 
->next 
->next • 



len 



da tap 



nxt 



* Application-specific Network handle 
*/ 

typedef struct EwaNetHandle s EwaNetHandle^t, "EwaNetHandle; 
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«de£ine EWA_NET__HANDLE_NUtL { (EwaNetHandle) HULL) 
/* 

* Application>specific netvoik handle cleanup function (ox macxo) 

* Invoked by EmWeb/Servei aftei each pzocessing each HTTP xeguest 

* before invoking evaNetHTTPEndO . 
*/ 

#ifndef EW_CONFIG_OPnON__FILE_GET 

#define ewaNetHTTPCleanup( handle ) /* no cleanup necessary •/ 
«eDdif 

/• 

* ;^plication- specific Documenc handle 
•/ 

cypedef void * BwaCocumentHandle; 

#define EWA_DOCUMENT_HANDLE_NULL ( (EwaDoCUWentHandle) MULL) 

«ifdef EW_C0NFIG_0PnON_AUTH 
/* 

* AUTHORIZATION 
« 

The application may attach an application- specific handle to an entry 

* in the authentication database. .The C-type foi this handle is defined 

* by the application below, 
*/" 

typedef void * EwaAuthHandle; /• user handle to ID entry •/ 

#define EWA_AUTH_HANDLE_NULL t (EvaAuthHandle) NULL) 

fiifdef EW_CONFIG OPTION_AUTH_D1GEST 
/• 

* Application -specific nonce paiameteis - these are used for Digest 

* authentication to generate one- time challenges. Recommended values 

* include the client's IP address (derived from the network handle), 

* a time -stamp, a server -side secret value, and other random bits and 

* pieces. The EmWeb/Server generates an KD5 hash on these values (hiding 

* their semantics) to create the nonce value sent as challenges. 
•/ 

typedef struct EwaAuthNonce^s 
{ 

uint32 client__ip; 
uint32 tinescanp; 
uint32 up_countei; 
If define ewa_AUTH_SECRET_SIZE 8 

char secret tEWA_AUTH_SECRET_SIZE] ; 

) EwaAuthNonce; 

«endif /* ew_cohfig_option_auth_digest •/ 

#endif /• EK_CONFIG_OPTION_AUTH */ 
/• 

* RAW CGI INTERFACE 

* The application may attach an application- specific handle to a raw CGI 
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* request. The C-cype for this handle is defined by the applicacion belov. 
•/ 

cypedef void * £waCGIKandle; 

(jdeCine EWA_CGI_HANDLE_NULL ( (EvaCGlHandle) NULL) 
/* 

* LOCKING 
• 

* The following cmczos must be defined to disable and enable ,&asl<; pteemption 

* to protect critical regions if more than one pre-emptive task may access 

* EmWeb/Servei API functions at the same time. 

((define EWA_TASK_LOCK ( ) 
#define EWA_TASK_UNLOCK ( ) 

/• 

* GLOBAL STATE 
•/ 

typed ef struct EwsScate_s *Ew5StaceP; 
/• 

* The ews state is a pointer to global state information used internally 

* by EmWeb/Sexver . In some environecnents^ it may be desirable to maintain 

* multiple threads of EmWeb/Server vithin a single memory. To support this 

* functionality, ews^state may be overridden by a macro that expands at 
*. run* time to different values. The only requirement is that the macro 

* returns type tEwsStateP) , and that the address of the pointer {&ews_state) 

* can be determined. For example: 

* ftdefine evs state (* ( (EwsStateP* ) someFunction (someAigument) ) ) 
♦/ 

* LIBRARIES 

* The EmWeb/Servei implementation uses the following standard C library 

* functions: 

* spiintf • for converting decimal integers to strings, needed to 

* generate Content -Length: HTTP headers. 

* strcpy - for copying null • teiminated strings between the application 

* and the EmWeb/servei (usually URL names) . 



atrcmp - for comparing null' terminated strings (comparing URL names) . 
strlen - get size of string 

Most embedded environments have these functions available in libraries. 
However, EmWeb/Server can be configured to provide its own internal 
implementations for this purpose. (Note that a general sprintf 
implementation is not provided. Instead, only a conversion routine from 
long integers to strings is needed. 

The following macros should be defined (ftdefine) if the corresponding 
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• function is piovided by the application environment. 
•/ 

#undef EMWES_KAVE_SPRINTy 
«undef EMWEB~HAVE_STRCPY 
Kundef EMWEB~KAVE_STRCMP 
#undef EKWEB~HAVE_STRLEN 
ffundef EMWEB][HAVE_MEMCPy 
Uundef EMWEB_HAVE__MEMSET 
Itundef EMWEB_HAVE_STRCHR 

/♦ If you have 'index' but not 'strchr'. define EMWEB_HAVE_STRCHR and 

• ftdefine EKWEB_STRCHR(s,c) index ts,c) 

#i£dcf EW CONF1G_OPTION_FILE 

• SERVER FILE SUPPORT 
* 

• For support of a server side file system, 
•/ 

cypedef struct EwaFileHandle_s •EwaFileHandle; 
(tdefine EWA_FILE_HAHDLE_JIUI-L ( (EwaFileHandle) NULL) 

*tif defined t EW_CONFIC_OPTION__riLE_GET ) \ 

II defined ( ek_config'option_file_put ) \ 

II defined { ew_config^OPTIOH_FILE_DELET£ ) 
typedef void -EwaFileName; /• unused for now •/ 

ftendif /• ew_config_optio«_file_xxx */ 

«endif /• EW~CONFIG_OPTION_FILE •/ 
sendif /• EW C0HFIG_H •/ 



A-2. Common Header Files 

The header files provided here may be included by application software and define the 
application interfaces to the EmWeb/Server. 

A-2,1. src/include/ews_api.h 

This is a master include file for EmWeb/Server which, in turn, includes all other 
application interface header files. We recommend that applications include this file for 
ease of integration with future releases. 

/• 

* ews_api.h,v 1.12 1997/05/21 21:55:43 laa Exp 
* 

• Product: EmWeb 

♦ Release: R2___l 
« 

• CONriDENTIAL AND PROPRIETARY INFORMATION OF AGRANAT SYSTEMS, INC. 
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Copyright (C) 1996, 1997 Agianac Systems, Inc. 
All Rights Reserved 



Agranat Systems, Inc. 
1345 Main street 
Waltham, MA 021S4 

(617) 893-7B68 

salesffiagranat.com, supportsagranat .com 
http : //wwv . agrana t . coji/ 
EmWeb/Server Application Interface 



ftifndef _ 


_EWS_API_H 






#define ' 


]ews~api~h 






(finclude 


'*ew_types .h" 




application-defined generic types 


^include 


'*ew_conf ig.h" 




application -defined configuration 


trinclude 


"ews_def .h" 


/• 


general interface definitions •/ 


t^include 


"ews_sys .h" 


/• 


system interfaces •/ 


^include 


"ews_net,h" 


/» 


network interfaces •/ 


^include 


''ews_doc,h" 


/• 


document interfaces */ 


^include 


'•ews_auth,h" 


/* 


authentication interfaces */ 


# include 


" ews_cgi . h" 


/* 


CGI interfaces ■/ 


#include 


"ews_ctxt.h" 


/• 


context access interfaces */ 



ttendif /• EWS API H •/ 



/ 



A-2.2, src/include/ews_def.h 

This file contains general definitions used throughout the EmWeb/Server application 
interface. 

ews_def.h,V 1,26 1997/05/25 23:30:32 giusti Exp 

Product: EmWeb 
Release: R2_l 

CONFIDENTIAL AND PROPRIETARY INFORMATION OF AGRANAT SYSTEMS, INC. 
THE EMWEB SOFTWARE ARCHITECTORE IS PATENT PENDING. 
EMWEB IS A TRADEMARK OP AGRANAT SYSTEMS, INC. 

Copyright (C) 1996, 1997 Agranat systems, Inc. 
All Rights Reserved 
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« Agzanat Systems. Inc. 

* 1345 Main Street 

• Walthatn, MA 02154 



• (617) 893-786B 

• salesSagxana t . com, suppoz tOagzana t . com 



* 



* hCtp://wwi.agranat.coDi/ 

• EmWeb/Sezvei public definitions 
« 

#ifndef _ews_def_h 
ftdefine ~EWS~DEF_H 

typedef const chai *EwsConstCharP; 
/• 

• Status codes letuined to the application by EmWeb/Servei 

typedef enum EvsStatus_e 

{ 

EWS_STATUS_OK, 
EWS~STATUS_BAD_MAGI C , 
■ EWS~STAT0S~BAD~VERSION, 
EWS~STATUS_ALREADY_EXISTS , 
EWS_STATUS_NO_RES0URCES , 
EWS~STATUS~IN_USE , 
EWs3sTATUS~H0T_REGISTERED , 
EWS"STATUS~H0T_CL0NED , 

ews_status_not~found , 
ews_s tatus_auth_fai led , 
ews~status_bad_s tate , 
ews"status~bai>_realm , 
ews~status"fatal_error , 

EWS_STATUS_ABORTiD 
J EvsStatuS; 

/• 

* Status codes xe turned to BmWeb/Sezvei by the application 
•/ 

typedef enum Ewastatus e 
( 

ewa_status_ox, 

# ifdef EW_CONFiG_OmON_SCHED 
EWA_STATUS_OK_YiELD , 

# endif ~ 

EWA_S TATUS_ERROR 
} EvaStatus; 
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* EtnWeb/Servez requesc concexc handle 
•/ 

typedef struct EwsContext_s * EwsContext; 

fidefine EWS_CONTEXT_KULL t (EwsConcext) NULL) 

#ifdef EWA_LOC_HOOK 
/* 

* Scatus codes used fox logging lequests 
•/ 

cypedef enum EvsLogstacus e 
{ 

/• 

* 200 Request accepted 
*/ 

EWS LOG STATUS OK, 



Request dispositions {after successful request) 



EWS_LOG_STATUS_NO_CO}ITENT , 

ews_log~status_moved_perkanently, 
ews~log_status_moved_temporarily, 
ews~log"status_see_other, 

EWS_LOC_STATUS~NOT~MODrriED, 
/• 

* 401 Unauthorized 

EWS_LOG_STATUS_AUTH_F AILED , 

EWS_L0G~STA7US_AUTH_F0RGERY , 

EWS_LOG~STATUS_AUTH_STALE , 

EWS_LOG_STATUS_AUTH~RE0UrRED, 

EWS "log "status "AUTH*blGEST REgUIRED , 



/* 204 no-op form or imagemap */ 
/♦ 301 link V 
/* 302 redirect •/ 
/* 303 see other •/ 
/• 304 not modified since •/ 



/" authorization failed •/ 
/• bad message checksum */ 
/' authorization nonce stale •/ 
/• authorization not present •/ 
/• message digest not present •/ 



* 400* Bad Request 
*/ 

ews_loc_status_bad_reouest , 
ews_log~status_bad2form , 
ews~log"status~bad imagemap. 



/* HTTP parse error •/ 
/• form data parse error •/ 
/• imagetnap query parse error */ 



* Additional errors 

ews_log_status_not_found, 
ews_log_status"method_hot_allowed , 
ews"log~status_length~reouired, 
ews_log_status~unavailable, 
ews_log_status_not_implemented , 
ews_log_status_ho_resources , 

EWS LOG status INTERNAL ERROR 



/« 404 not found or hidden •/ 
/• 4 OS method not allowed •/ 
/* 411 length required •/ 

/• 503 aborted Document Fault ' 
/• 501 bad method for URL •/ 

/• 500 insufficient resources ' 
/• 500 internal error •/ 



} EvsLogStatus; 
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/* 

* ewaLogHook 

* Applicacion logging hook 
« 

* context - context of request being logged 

* status ' logging status 
•/ 

ffifndef evaLogHook 

extetn void evaLogHoo]c (EwsContext context, EvsLogStatus status); 
«endi£ /* evaLogHook •/ 

*telse /* EWA_LOG_HOOK */ 

^define evaLogHook (context, status) 

l^endif /* EWA_log_hook */ 

/• 

* EmWeb/Sexvei archive descriptor. 
*/ 

typedef struct EwsArchive_^s • Ei*'sArchive; 

* EmWeb/Seiver document handle 
•/ 

typedef struct EwsDocunient_s • EvsDocument ; 

((define EWS_DOCUMENT_NULL ( {EwsDocument} NULL) 

/• 

* EmWeb/Server opaque read -only da lb handle 
*/ 

typedef const uints EvsAxchiveData [] ; 
/• 

* EmWeb/Servei authorization handle 
*/ 

typedef scrucc EvsAuthHandle_s • EwsAuthHandle; 
ftdefine EWS AUTH HANDLE NULL~ ((EwsAuthHandle) NULL) 



constants for status byte 

0x01 
0x02 
0X10 
0X20 

0x20 /* equivalent to parse error */ 

/* 

• EmWeb/server form element types 
•/ 

«i£def EW_CONFIG_OPTION_FIELDTyPE_HEX_STRrNG 
typedef struct EwsFormFieldHexStiing_5 
{ 

uint32 length; 



(fitdef EW CONFIG_OPTION_F0RM 
/• 

* Application form interface 
*/ 

(tdefine EW_FORM_INITIALIZED 
«define EvTformJJYNAMIC 
«de£ine EW^FORM^RETURNED 
Kdefine EW_FORM~PARSE_ERROR 
ftdefine EW^FORM FILE iRROR 
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uinC8 *dacap; 
} EwsFormFieidHexscring, •EwsForaiFieldHexScringP; 
ttendif /* EW__CONFIG_0PTI0N_FIELDTYPE_HEX_STRING */ 

»if (defined(EW_CONFIG_OPTION_FIELDTYPE_IEEE_MAC) \ 
I I def itiedTBW_C0NFIG_0PTI0N_FIELDTyPE_F5DI_MAC) \ 

It defined {ew_config2option_fieldtype~std_mac) a 

) 

cypedef uintS BwsPozinFieIdMAC{6] : 
(fendif /• MAC ♦/ 

tfifdef EW_C0NFIG_0PTI0N_FIE1DTVPE_0ID 
cypedef scxuct £wsFoxinFieldObjecLXD_s 
I 

uinC32 length; /* number of uinc32's in datap */ 

uint32 "datap; /* array of uint32's reptesencing OID •/ 

} EwsFoimFieldObjectID, ■'EvsForinFicldObjecclDP; 
#endif /• EW_CONFIG_OPTION_FIELDTYPE_OID •/ 

#if defined (EW_COHFIG_OPTION_FIEl.DTYPE_RADIO) || \ 

defined tEW_CONFIG~OPTION~FIELDTYPE_S ELECT SINGLE) 
/• ~ 

• ewsForttiEnutnToScring 

• Lookup string corresponding co enun from context 
« 

• context - context of request 

• enum • value of enumerator 
* 

• Returns string from corresponding HTML VALUE- field, or NULL if out of 

• bounds . 
*/ 

extern const char • ewsFormEnumToString ( EvsContexc context, int value ); 
Itendif /• EW_CONFIG_OPTION_FIELDTYPE_RADIO 1 SELECT_SINGLE •/ 

ffendif /* EW_C0HFIG_0PTI0N_F0RM •/ 
/* 

• EwsRequestMethod 
« 

• This is an enum for supported request methods. Bit values are used so 

• groups of valid request methods can be grouped into a single field 
V 

typedef enum EwsRequestMethod_e 
{ 

ewsRequestMethodunknown • 0x0000 /• all others */ 
,evsRequestMethodGet » OxOOOi /• GET */ 
,ewsReque5tMethodPost ■ 0x0002 /* POST */ 
,ewsRequestMethodHead * 0x0004 /* HEAD */ 

« ifdef EW_C0NFIG_OFTION_METHOD_OPTI0NS 

,evsRequestMethodOptions - oxooos /* OPTIONS */ 
# endif 

» ifdef EW_CONFIG_OPTION_METH0D_TRACE 

.ewsRequestMethodTrace ■ OxOOlO /* TRACE •/ 
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ft endif 

ifdef EW_CONriG_OPTION_METHOD_PUT 
.ewsRetjuestMethodPut ■ 0x0020 /• PUT •/ 
ft endif 

*t ifdef EW_CONFIC_OPTION_METHOD_IJELETE 

,ewsRequescMeLhodDelece - 0x0040 /• DZVSTE «/ 
« endif 

) EvsKeque s CMe thod ; 



ftendif /* EWS DEF H */ 



A-2.3. src/include/ews_sys.h 

This file contains definitions and prototypes of the system functions of the application 
tntertace. 

. ♦ ew6_sys.h,v 1.17.2, 3 1997/06/02 23:46:39 giusti Exp 

• Product: EtnWeb 

• Release: R2_i 

• CONriDENTIAL ANT PROPRIETARY INFORMATION OF AGRANAT SYSTEHS. INC. 

• THE EhfWEB SOFTWARE ARCHITECTURE IS PATENT PENDING. 

• EMWEB IS A TRADEMARK OF AGRANAT SYSTEMS, INC. 

• Copyright (C) 1996, 1997 Agranat Systems, inc. 

• All Rights Reserved 

Agranat Systems, Inc. 

• 1345 Main Street 

• waltham, MA 02154 

• t617) 893-7B6B 

• saleseagzanat.com, supportSagianAt .com 

• httpi // WW. agranat. com/ 

• Etnweb/Servei system interfaces 
•/ 

(fifndef _Ews_SYS_H 
Ifdefine 2ews_SYs][]h 

# include " ew_ types. h" 
^include "ew^conf ig.h" 
#include "ews def.h" 
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* INITIALIZATION AKD SHUTDOWN 
• 

* The EmWeb/Server must be Inicialized at start-up before accepting requests, 

* installing document archives* or legistering auchencication information. 

* / 

/« 

« evslnic 

* Initialize EmWeb/Server 
• 

« Re earns EWS_STATUS__OK on success, else failure code (TBD) . 
•/ 

extern EvsStatus ewslnit ( void ); 

tfifdef EW_CONriG OPTION_CLEANUP 
/* 

* ewsshutdown 

* Graceful shutdown of EmWeb/Server cerminacing all requests in progress 

* and releasing all memory and buffers. 

m 

* Returns EWS_STATUS_OK on success, else failure code (TBD) . 
*/ 

extern EwsStatus ewsshutdown ( void ) ; 
#endif /• £W_C0HFIG_0PTI0N_CLEANUP •/ 

Itifdef EW CONFIG OPTION SCHED 

/ 7 , 

» 

* SCHEDULING 

* The EmWeb/Seiver is capable of both multi - threading HTTP requests and 

* yielding execution control to the CPU. The following functions are provided 

* to give the application control over how EmWeb/Server schedules pending 

* requests. 

- / 

/* 

* ewsRun 

* Reschedule request processing after control returned to application as a 

* result of returning EWA_STATUS_OK_yiELD from ewaNetHTTPSendO , 

* ewaNetKTTPEndO . ox ewaDocumentFault () , or as the value to the status 

* parameter in ewsResumeO- 
• 

* Returns EWS_STATUS OK on success, else failure code (TBD) . 
extern EwsStatus ewsRun ( void ) ; 

ftifdef EW_C0NF1G_0PTI0N_SCHED_SUSP_RES 
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* evsSuspend 

* Suspend piocessing of the cuizent zequesL duzing an EmWeb callout funciion 
» (e.g. EmWebSciing , EmWebFoimSeive, or EmWebFoimSubmic) . This function is 

* used in the implementation of proxies. 
• 

• jJote that this does _not_ cause the server to stop piocessing lequests; in 

• fact, it forces a flush of any paiCially filled buffer for the current 

• request and may process other pending requests. This just causes the 

* current callout to be marked as 'suspended'. When the cuizent callout 

* letuins, the result vill be ignored - after ewsResume (below) is called 

* for this same context, the callout vill be repeated. 
« 

■ context - context of request to be suspended 

• 

• Returns EWS_STATUS_OK on success, else failure code (TBD) , 
extern EwsStatus evsSuspend ( EvsContext context ) ; 

/* 

• evsResume 

• Resume processing of a request previously suspended by ewsSuspendO- This 
« causes the request to be rescheduled, and the callout from which evsSuspend 

• had been called will be leinvoked, 
* 

• context • Context of suspended request to be resumed 

• status • EWA_STATUS_OK 01 EWA_STATUS_OK_YIELD . 

•* 

* Returns EWS_STATUS_OK on success, else failure code (TBD) . 
*/ 

EvsStatus evsResume ( EvsContext context, EvaStatus status ); 
Hendif /* EW_C0NFIG_OPTION_SCHED_SUSP_RES */ 

*tendif /• EW_C0NFIG_OPTION_SCHED •/ 

- • • 

• MEMORY MANAGEMENT 
* 

• The EmWeb/Server presumes that the target 0/S has a dynamic memory 

* management capability roughly equivalent to the P05IX mallocO and freeO 
« functions. 

•* 

* Alternatively, the application could create a static linked- list of memory 

* blocks of different sizes. Refer to the product documentation for 

* information abput run- time memory requirements. 
■ * 

* The application is responsible foi providing the fol loving memory management 
.* functions to the EmWeb/Servei . 

• •••• * / 

ttifndef evaAlloc 

• evaAlloc 
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* Allocace a block of memory of at least the requested number of bytes. 

* bytes • requested size of the memory block in byces 

* Ke turns a pointer to Che first byte of memory, or NULL if no memory of the 

* requested size is available. 

•/ 

extern void * evaAlloc { uintf bytes ) ; 
tfendif 

tfifndef ewaFree 
/* 

* evaPiee 

* Free a block of memory previously allocated by ewaAllocO 
• 

* pointer - pointer to beginning of memory block (from ewaAlloc(}) 
« 

* No return value 
*/ 

extern void ewoFree ( void * pointer ) ; 
«endiC 

Sifdef EW CONFIG OPTION DATE 



* TIME -OF* DAY MANAGEMENT 
« 

* If DATE support is enabled, the EmWeb/Server invokes the following 

* application -provided function to retrieve the current date for use in 

* Date: HTTP headers. Furthermore, the current date is also used in 

* Expire: and Last -modified: headers of dynamically generated documents 

* (i.e. HTML documents containing EMWEB extensions), if configured. 

* Note that the Last -modified: header of static documents use. the archive 

* creation date stored in the archive by the EmWeb/Compiler . 



#ifndef ewaDate 
ewaDate 

Return a string containing the current time-of-day in one of the HTTP 
standard representations as follows: 

RFCX123: .(Piefeired standard) 
Fti, 28 Jun 1996 15:57:28 GMT 

RFC8S0: (Used, but not preferred) 
Friday, 2a-Jun-96 15:57:28 GMT 

asctime: (Allowed, but discouraged) 
Jun 6 15:57:26 1996 

/ 
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extern const chai * evaBate ( void ) ; 
Ifendif 

#endif /• EW_CONFIG_OPTION_DATE ♦/ 
#ifdef EW_CONF3G_OPT10N__URL_HOOK 

/ 

• URL REWRrTING 



• If URL revriting support is enabled, the EmWeb/Seivex will invoke the 

• following function when each ie<iuest has been successfully parsed but 

• before the URL is looked up in the filesysteni. The application can then 

• return a new (or the same) url to actually serve 



«ifndef ewaURLHook 

• ewaURLHook 
• 

• context * context of request 
•ml - reciuested URL 

• Returns new URL, or NULL to cause abort. (For no-op, sinpiy return url) 

• Note; the application MUST NOT invoke ewsHetHTTPAbort from here- Retu-n 

• a NULL pointer instead; * *^'^'*"*" 

• The URL tr.ay be revTitten in place if the length is not increased- 

• If the returned pointer is not within the url parameter, the value is 

• copied by the server. 
V 

extern char • ewaURUiook ( EwsContext context, chai -url ); 
*tendi f 



»endif /• eh_config_option_log_hook •/ 
/* 

• Since content length of zero is valid, we cannot use zero to 

• indicate when the content length is unknown (eg. dynamic data) 

• Assuming nobody will ever try to send/receive a 4 gig document is 

• probably safe for now... 
•/ 

« define EWS_CONTENT_LEHGTH_UWKNOWN {(int32) -1) 

<fifdef ew coNnG_opnoN file 

/ , 

* 

• local file system support 

♦ 

• The following routines must be supplied to support the server's 

• local file system. 
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cypedef union Ew5FileParams_s 
{ 

/• 

• fileField - foi support of the form INPUT TYPE-riLE field. 

• The server filis ouc this stiuccure, and passes ic to 

• the application when the file is submitted 
•/ 

ft ifdef EW_CONFIG_OPTION_FIELI>TVPE_FILE 
struct 

i 

const char *fileNaine; /• file name or NULL •/ 

const char •contentType; /* MIME type •/ 

const char •contentEncoding; /* content encoding or NULL ♦/ 
const char *contentDisposition; /* Content -disposition: •/ 

int32 contentLengch; /* length or EWS CONTENT LENGTH UNKNOWN •/ 

] fileField; - - _ 

# endif /* EW_CONFIG_OPTION_FIELDTYPE FILE •/ 



• filelnfo - for support for local file operations (GET, HEAD, OPTIONS, 

• PUT, DELETE) . This Structure is setup by the application when a URL 
■ * that corresponds to a local file is received. This structure 

• gives the server all it needs to know to handle the file operation 
*/ 

U if defined t EM_CONFIG_OPTION_FILE_CET ) \ 

I I defined ( EW_C0NFIG_^OPTI0N_FILS_PUT ) \ 

II defined ( ew_config2o?TIon_file_DELETE ) 
struct ** 

{ 

EwaFileName fileName; /• file name (opaque) */ 

const char "contentType; /« MIME type •/ 

const char 'contentEncoding; /• content encoding or NULL •/ 

const char "contentLanguage; /• content language or NULL •/ 

const chax *eTag; /* reserved, must be NULL •/ 

const char • lastModif ied; /• modification time (RFC1123) or NULL •/ 

const char '•lastModi£iedl036 ; /• modification time (RFCia35) or NULL •/ 

const char -"realm; /• auth realm or NULL •/ 

int32 contentLength; /• length or EWS_content_LENGTH_UNKNOwn •/ 

EwsRequestMethod allow; /• reserved, MUST BE ewsRequestMethodGet ♦/ 

/• HEAD & OPTION _always_ allowed by default •/ 

) filelnfo; 

» endif /• local file system GET/PUT/DELETE ♦/ 

char reservedl; /• prevent NULL union •/ 

) EwsFileParams, *EwsFileParamsP; 



• ewaFileClose 
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« Closes the file and indicates success or failuie 
•/ 

extern void 

ewaFileClose ( BvaFileHandle handle, Ewsscatus status ); 
/* 

* evaFileWrite 

• Wiite data to a file 
*/ 

extezn sintf 

ewaFileWiite ( Bvscontext context 

, EwaFileHandle' handle /• handle from evaFileOpen •/ 
, const uintB *datap /• pointei to data ♦/ 

, uintf length /* length of data •/ 

) ; 

/• returns bytes written, <0 on erioi */ 
/• 

• evaFileRead 

^ Read data from a file 
•/ 

extern sintf 

ewaFileRead ( EwsContext context 

, EwaFileHandle handle /- handle from ewaFileOpen ♦/ 
, uintB 'datap /• pointei to data buffer •/ 

, uintf length /• length of buffer */ 

) ; 

/• returns bytes read, o on EOF, <o on error •/ 

*tifdef EW COMFIG_OPTION_FIELr>TYPE_FILE 
/• 

• ewaFilePost 

• For multipart/form -data file submissions. Befoze the application's 
" submit function is called, the server may invoke this function foi 

• each leceived file as part of a <INPUT TyPE*FILE> element in the 

* form. If successful, the file handle will be passed to the 

• application's submit function at which point it is the application's 

* responsibility to close the file. 
•/ 

extern EwaFileHandle 
ewaFilePost ( EwsContext context 

, const EwsFileParams "params 

) ; 

/' returns EWA_F1LE_HAMDLE_NULL on error */ 
(tendif /• EW_CONFIG~OPTION_FIELDTyPE_FILE ♦/ 

tfifdef EW_C0NFIG_OPTION_FILE GET 
/* 

* ewaFileGet 

* When the sexvez determines that the file set by ewscontextSetPile 

* should be served to the browser, this function is invoked to open 

• the file for reading. 
• 

* To support Conditional GET, the request message may include 
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* If -Modified-Since, If -Umnodified-Since, If-Macch, 

* If 'None -Match, or If -Range headers. In this case, the 

* server will use the information given in the recurned 

* params block to determine if the file should be retrieved. 
*/ 

extern EwaFiieUandle 
evaPileGet ( EwsContext context 
, const char 'url 

, const EwsFileParams -params /* from ewsContextSetFileO */ 
) ; 

/* returns EWA_FILE_HAKDLE_NOLL on error */ 
» end if /* EW_CONFIG_OPTION_FILE_GET •/ 

tendif /* EW_CONFIG_OPTION_FILE */ 

#endif /• EWS_SYS_H •/ 



A-2.4. src/inciude/ews_net.h 

This file contains the definitions and prototypes used by the networking functions of the 
application Interface. 

ews_net.h,v 1.20.2.1 1997/06/15 03:03:18 giusti Exp 

Product: Emweb 
Release: R2_l 

CONFIDENTIAL AND PROPRIETARY INFORMATION OF AGRANAT SYSTEMS, INC. 
THE EHWES SOFTWARE ARCHITECTURE IS PATENT PENDING. 
EKWEB IS A TRADEMARK OF AGRANAT SYSTEMS, INC. 

copyright (C) 1996, 1997 Agranat systems, Inc. 
All Rights Reserved 



Agranat systems, Inc. 
1345 Main Street 
Walcham, MA 02154 



(617) B93-7868 

sales»agr anat.com, suppoitaagranat.com 
http : / / ww , agr ana t . com/ 

EmWeb/Server application interface to network transport layer 



*/ 

ttifndef _EHSJTET_H 
^define ~EWS~NET_H 

^include "ew_typeB.h" 
Sinclude "ew config.h" 
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^include "ews^def.h" 



in a typical TCP/IP ImplementatiDn, che application is responsible for 
listening to the HTTP TCP port (80) for connection requests. When a 
!n!h,'tr.^Trwt^ received the application accepts the connection 
on behalf of EmWeb/Server and invoke ewsNetHTTPStart t) to inform the 
EmWeb/Server of the new request. intoim cne 

EmWeb/Server assumes that the application inaintains data buffers for 
^Iwc!'^'""-*"'^ transmission of TCP data. The only requirements that 
EmWeb/Server rmposes on the buffer implementation is as follows: 

1. Buffers can be uniquely identified by a buffer descriptor No 
assumptions are made about the actual structure of the buffer 
descriptors or their relationship to data. For example, a buffer 
descriptor could be an index into a table, a pointer to a 
structure (either contiguous or seperate from the data represented), 
etc. The application is responsible for defining the appropriate 
type for EwaNetBuffer and value foi EWA_NET_BUrFER_NUtI, . 

2. Buffers can be chained together. Given a buffei descriptor 
field. This is done by ewaNetBuf f erNextSct () and 

ewaNetBufferNextGetO Note that the buffei chain is terminated when 
the next buffer value is EWA_NET_BUrFER_NULL . 

3. Given a buffer descriptor, EmWeb/Server can determine the start of 
data in the buffer. Additionally, EmWeb/server may change the start 
of data in the buffer (EmWeb/Server only changes the start of data in 
the buffer upward). This is done by ewaNetBuf ferDataGet {) and 
ewaNetBufferDataSetO . 

4. Given a buffer descriptor, EmWeb/Server can determine the sire of 
contiguous data in the buffei. Additionally, EmWeb/Server may 
change the size of the buffer (Emweb/Servei only changes the 

size of the buffer dou-nward) . This is done by ewaNetBuf ferLengthGet 0 
and ewaNetBufferLengthSecO , xi.cii,engtnt»et w 

5. EmWeb/Server may allocate a buffer by invoking ewaNetBuf ferAlloc 0 

If no buffers aie available, this function returns ewa net BUFrER sult. 
Additionally. EmWeb/Server may release a buffer by ^okina " 
ewaNetBufferFreeO . 

AS the application receives TCP data on an HTTP connection, it' passes 
this data to the EmWeb/Server by invoking ewsNetHTTPReceive () . 

The EmWeb/Server transmits TCP data on an HTTP connection by invoking 
evaNetHTTPSendC) . The application- may throttle EmWeb/Server by 
returning EWA_STATUS_OK_yiELD . This causes the EmWeb/server to 
save state and return control to the application. The application must 
invoke ewsRunO to give the EmWeb/Server an opportunity to continue 
processing the recjuest. 
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* when the EmWeb/Server completes a xequest. it invokes ewaNecHTTPEndO . 
* 

* The application may abort a xequest at any time by invoking 

* ewsNetHTTPAboit(} . " 



* ewsNetHTTPScart 

* Start a new HTTP request 

* net__handle - application -specific handle representing request 
* 

* Returns context for the request, oi EWS_COKTEXT_NULL on failure, 
extern EvsContext ewsNetHTTPStart ( EwaNetHandle net_handle ) ; 

/• 

* ewsNetHTTPAbort 

* Abort a previously started HTTP request. 

* context • context of request to be aborted 

* Returns EWS_STATUS OK on success, else error code (T3D( 
•/ 

extern EwsStatus ewsNetHTTPAbort ( EwsContext context }; 
/• 

* ewsNetHTTPReceive 

* Receive request data from the network. 
* 

* context - context of request to which received data applies 

* buffer ■ buffer containing received data 
* 

* Returns EWS_STATUS OK on success, else error code (TBD) 

extern EwsStatus ewsNetHTTPReceive ( EwsContext context, EwaNecBuffer buffer ); 

ftifdef EW_CONFIG_OPTION_SCHED_FC 

/* 

* ewsNetFlovContxol 

* Mark context for flow control to avoid predicted congestion. ewsRunO will 

* place the context on the suspended list at Che next opportunity and 

* continue by {Processing additional requests. 
• 

* context - context of request to be flow controlled 
* 

* Returns EWS STATUS_OX. 
*/ 

EwsStatus ewsNetFlovContxol ( EwsContext context ) ; 
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* ewsNetUnPlovConcrol 

* Resume previously flow contiolled context 
• 

« context • context of zequest to be flow contiolled 

« 

* Returns EWS STATUS_OK. 

EvsStAtus ewsNetUnFlovContiol ( EwsContext context ) ; 
#endif /• EW_CONFIG_OPTION_SCHED_PC •/ 
#ifndef ewaNetHTTPSend 

* ewaNetHTTPSend (Application) 

* This function must be provided by the application to accept data fzom 

* EmWeb/Servez fox tiansmission to a brovsei in response to a request. 
* 

* net_handle • application-specific request handle from ewsNetHTTPStaitO 

* buffer • buffer containing data to be transmitted 
« 

* Returns EWA_STATUS_OK on success , •IWA_STATUS_0)t_yiELD on success and 

* request EmWeb /Server to yield CPU to application, or EWA_STATUS_ERROR on 

* failure. 
•/. 

extern EwaStatus ewaNetHTTPSend 

( EwaNetHandle net_handle, EwaNetBuffer buffer ) ; 
«endif 

(Jifndef ewaNetHTTPEnd 
/* 

* ewaNetHTTPEnd (Application) 

* This function must be provided by the application. It is invoked by 

* EmWeb/Server to indicate the completion of a request after all response 

* data has been sent. 
« 

* net_handle - application- specif ie request handle from ewsNetHTTPStaitO 

* Returns EWA__STATUS_OK on success, EWA_STATUS_OK__yiELD on success and request 

* Eo)Web/Seive7 to yield CPU to application, or ewa_STATUS ERROR on failure. 

extern EwaStatus ewaNetHTTPEnd ( EwaNet Handle net_handle ); 
#endif 

Kifndef cwaNetBuf ferAIloc 
/* 

* ewaNetBuff ex Alloc (Application) 

* This function must be provided by the application. It is invoked by 

* EmWeb/Server to request a network buffer to be used for sending data. 
* 

* Returns a buffer, or ewa_HET_BUFFER_NULL on failure. The length of the 

* buffer must be initialized to the number of bytes available for use 

* by EmWeb/Server. 
•/ 

extern EwaNetBuffer ewaNetBuff eiAlloc ( void ) ; 
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«endif 

#ifndef ewaNeCBuf feiFxee 
/• 

• ewaNetBuffeiFree (Application) 

• """^ provided by the application. It is invoked by 
EmWeb/Servei co release one or a chain of network buffers (either from 

• ewsNetHTTPReceivet) or ewaNetBuf ferAlloc () ) lextner rrom 



buffer 



- buffer (s) to be released 



• No return value 



extern void ewaNecBuff erFree ( EwaNetBuffer buffer ) • 
#endaf 



ftifndef ewaNetBuf ferLengthGet 
/* 

• ewaNetSufferLengthGet (Application) 

I 1^^^^"^'='^^°" provided by. the application, it is invoked by 

* EmWeb/servei to get the length of the data portion of this buffer fiagmenc. 

• buffer ■ buffer descriptor 

* Returns length of buffer 
•/ 

uintf ewaNetBuf ferLengthGet ( EwaNetBuffer buffer ) ■ 
»endif 



ftifndef ewaNetBuf £ei Lengths et 
/• 

• ewaNetBufferLengthSec (Application) 

• This function must be provided by the application, ic is invoked by 

• ^^'^^Servei to set the length of the data portion of this buffer fragment 
This function is only used to decrease the original length of a 

• buffer. EmWeb/Server never increases the length of a buffer. 

• buffer - buffer descriptor 

• length • new length value 

• No return value 
•/ 

void ewaNetBuf ferLengthset ( EwaNetBuffer buffer, uintf length ) • 
(tendif 3 ' » 



ffifndef ewaNetBufferDataGet 
/• 

• ewaNetBuf feiDataOet (Application) 

• This function must be provided by the application. It is invoked by 

• EmWeb/Server to get the pointer to the data contained in the buffer. 

• buffer -buffer descriptor 
« 

• Returns pointer to data in buffer 
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uinte ♦ ewaNetBuffeiDacaGet ( EvaNetBuffer buffer ); 
«endif 

ttifndef ewaNetBuf feiDacaSet 
/• 

• ewaNeCBuffezOacaSec (Application) 

* This function must be provided by the application. It ie invoked by 

• EmWeb/Server to set the pointei to the data contained in the buffer. 

• This function is only used to advance the start of data forward. 

* EmWeb/Server never moves this pointer backward. 
« 

• buffer - buffer descriptor 

• datap - new start of data value 
• 

* Ho return value 
•/ 

void ewaNetBufferDataSet ( EwoNecBuffei buffer, uinc8 -datap ); 
ifendif 

Kifndef ewaNetBuf ferUextGet 
/* 

• evaNetBufferNextCet (Application! 

♦ This function muse be provided by the application. Ic is invoked by 

- EmWeb/Server to gee the next buffer descriptor in the buffer chain. 
« 

• buffer - buffer descriptor 
« 

• Returns next buffer descriptor, or ewa NET BUFFER NULL if end of chain 
./ - _ , 

EwaHetBuf fer ewaNetBufferNexcGet ( EwaNetBuff er buffer ) ; 
*endif 

#ifndef evaNetBuf ferNextSet 
/* 

* ewaNetBuf ferNextSet (Application) 

* This function must be provided by the application, it is invoked by 

* EmWeb/Servei to set the next buffer descriptor in the buffer chain. 

♦ buffer - buffer descriptor 

• next - next buffer descriptor to be attached to buffer 
* 

* No return value 
*/ 

void ewaNetBuf ferNextSet f EwaNetBuff ei buffer, EwaNetBuf fer next 1- 
♦endif 

ffifndef ewaNetLocalKostName 
/* 

* evaNetLocalHostName (Application) 

• This function must be provided by the application, it is invoked by the 

* EmWeb/Server to build proper redirection (Location:) headers. This can 

• be either a dotted IP address or a fully qualified^ hostname. 
*/ 
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const chax • ewaNetLocalHostName i EwsContext cone ex c ) ; 
tfendif 

#l£nde£ ewaNetHTTPCleanup 
/• 

* ewaNecKTTPCleanup 

* This function roust be provided by the application oi defined as a 

* enipty macio. Ic is invoiced by EmWeb/server when a request completes, 

* allowing the application to reset any processing state stored in the 

* networlc handle. Note that for HTTP l.l persistent connections, this 

* routine may be called several tiroes for the same connection, as one 

* connection can be used for multiple requests. For the last request 

* on a connection, this routine will be called before ewaUetHTTPEnd is 

* invoked. 



* Returns void. Note that the request context is undefined during 

" this call and cannot be accessed. 

V 

void ewaNetHTTPCleanup ( EwaNetHandle handle }; 
«endif 

ftendif /• _EWS_NET_H •/ „ 

A-2.5. src/incIude/ews_doc.h 

This file contains the definitions and prototypes for the archive and document 
management functions of the application interface. 



ew5_doc.h,v 1.20 1997/05/21 21:55:44 ian Exp 

Product ; EmWeb 
Release : H2_l 

COHriDENTIAL AKD PROPRIETARY INFORMATION OF AGRANAT SYSTEMS, IHC. 
THE EMWEB SOFTWARE ARCHITECTURE IS PATENT PENDING. 
EMWEB IS A TRADEMARK OF AGRANAT SYSTEMS, IHC. 

Copyright (C) 1996, 1997 Agranat Systems, Inc. 
All Rights Reserved 

Agranat Systems, Inc. 
1345 Main Street 
Waltham, MA 021S4 

(617) B93-7868 

salesffagranat . com, supportaagranat.com 
hctp ! //www . agrana t , com/ 

EroWeb/server application interface to document archives 



* 



/ 



/ 
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#ifndef __EWS_IJOC_H 
#de£ine "ews~DOC_H 

flinclude "ew^cypes .h** 
ifinclude "ew^^conf ig .h" 
^include "evs def.h" 



/ * * 

• ARCHIVE MAINTENANCE 
* 

• The EmWab/Coinpilei generftCes an oichive of one or moie documents. Documents 

• can be HTML files, JAVA piograms, graphical images, oi any other information 

• resource addressable by a URL. Archives may be independently loaded or 

• unloaded into the EmWeb/Seiver . 
« 

• In most applications, the entire set of available documents would be 

• compiled into a single archive and loaded at boot time. However, some 

• applications may desire to dynamically load archives at run-time as needed 

• in order to reduce memory requirepients . In fact, some applications may 

• want to implement a scheme similar to page swapping under some operating 

• systems to cache an active sec of documents in memory while storing other 

• documents in a secondary storage area. Such a secondary storage area 

• could be in FLASH memory, or on a remote server using TFTP or other 

• protocols to load documents at run-time. 
• 

• An EmWeb archive consists of two components. First, there is the archive 

• data component containing the database of compressed documents, information 

• about how to construct dynamic documents at run -time, access controls, 

• etc. Second, there is the archive object component containing the run -rime 

• object code used for the construction of dynamic documents, etc. 

• Operating systems supporting the run- time loading and linking of object 

• code may offload both the data and object archive components to a secondary 

• storage area. Otherwise, only the data components would be offloaded 

• while the object components would be statically linked into the run -time 

• executable image. 
• 

• Each archive contains an archive descriptor in the object component. The 

• archive descriptor is referenced by a public symbol generated by the 

• Emweb/Compiler . In order to activate an archive at run- time, the 

• application must invoke ewsDocumentlnstallArchive () with parameters 

• indicating the address of the data component and the archive descriptor of 

• the object component. The archive may be deactivated by invoking 

• evsDocumentRemoveAr chive () . 
* 

/ 

/• 

• ewsDocumentlnstallArchive 
* 

• Install a document archive generated by EmWeb/compiler into EmWeb/Server 

• xun'time database. 
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» desciipcox • public symbol of archive object component descriptoi 

* da tap - pointer to archive data component 
• 

* Returns EWS_STATUS_OK on success, else error code (TBD) 

extern EwsStatus evsDocumentlnstallAr chive 

£ EvsAichive descriptor, EwsArchiveData datap ); 

(tifdef EW_CONriG_OPTION_CLEAlIUP 

/• 

* evsSocumentEemoveAr chive 
* 

* Removes previously installed document archive fiom run -time database. 

* descriptor - public symbol of archive object component descriptoi 
• 

* Returns EWS_STATUS_OK on success , else error code (TBD) 

extern EwsStatus ewsDocumentRemoveAr chive t EvsAichive descriptoi ) ; 

«endif /* EW_CONF1G_OPTION_CLEANUP •/ 

/• 

* ewsDocumentAlchiveName 
• 

* Returns the archive name as stored in the archive by the EmWeb/cotnpiler . 

* or NULL on error . 
*/ 

extern const char ' ewsDocumentArchiveName ( const uintB * da tap ) ; 
/• 

* ewsDocumentArchiveDate 

* Returns the RFC1123 date string stored in the archive header generated 

* by the EmWeb/compiler when the archive was created, or NULL on erroi. 
• 

* There is also a routine for the less preferred RFC1036 representation. 
V 

extern const char * ewsDocumentArchiveDate ( const uints •datap ) ; 
extern const char * evsDocufflentArchiveDatel036 ( const uinte *datap ) ; 

«ifdef EW_CONFIG_OPTI0N_DEMAHD_L0ADING 

/ 

* DEKAtm LOADING 
« 

* In or del to implement on-demand archive loading, the application may 

* register document URLs with the EmWeb/server which are valid but not 

* loaded. This is done by invoking cvsDocumentRegister () . if a registered 

* document is requested, the EmWeb/Seivei will notify the application by 

* invoicing ewaDocumentFault{} . At this point, the application may load 

* a new archive {possibly removing a previously installed archive to make 
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* zoom) . When rhe ax chive containing the page is installed, the EmWeb/Servei 

* will automatically complete piocessing the zequest. The request can' be 

* aborted either immediately by returning EWA_STATtis_ERllOR from the 

* ewaDocumentPault ( } function, or by invoking ewsMetHTTPAbort (} . 

* Once a document is registered, there is no need to le -register it in the 

* event chat the corresponding archive is removed. EmWeb/Servex remembers 

* that the document has been registered as dynamically loadable. However, 

* the application may deregiscer a document by invoking 
« ewsDocumentDeregister O . 

• 

/ 

/* 

* ewsDocumentRegister 

Registers the URL of a document vith the run -time database indicating that 

* the given document is valid but not currently loaded into memory. 

* uxl • local URL of document to be registered 

* handle • application-specific handle passed to ewaDocumentFault () 

* Returns document desciiptoi, or EWs DOCUMENT_mJLL on failure. 
*/ ' " . 

extern EvsDocument ewsDocumentRegister 

( const char * url, EwaDocumentHandle handle ); 

* ewsDocumentDeregister 

* Unregisters a previously registered document from the run-time database 

* indicating that the given dynamically • loadable document is no longer valid. 
« 

« document • descriptor of document to be deregistered 

« 

* Returns EWS STATUS OK on success, else error code [TBD) . 
extern CwsStatus ewsDocumentDeregister ( EwsDocument document ) ; 
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^ifndef ewaDocumentFault 



ewaDocumentFault (Application) 

This function must be provided by the application, and is invoked by 
EmWeb/Server vhen a legistezed document has been requested but is not 
currently loaded into memory. 



context 
handle 



context of request fox document 

application*specific handle from ewsDocumentRegister ( ) 



Returns EWA_STATUS_OK on success, EWA_STATUS_0)<_VIELD on success with 
request for EmWeb/servei to yield the CPU, or EWA_STATUS_ERROR on failure. 
If failure status is returned, the request is aborted. Otherwise, the 
request will complete after the document has been loaded into memory. 

f 

extern EwaStatus ewaDocumentFault 

{ EwsContext context, EwaDocument Handle handle ) ; 
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fiendif /• EW_C0NF2G_0PTI0N_DEMAND_L0ADING •/ 
SiJdef EW_C0NFIG_0PTIOH_CLONING 

« 

• DOCUMEirr CLONIWG 



• Doc\iinencs may be cloned and assigned co a new URL. This allows tnulciple 

• instances of a document to exist. An application-specific handle can bv 

• used to identify an instance o£ a document from the request context, 
•» 

• The application clones a document by invoking ewsDocutnentClone () . The 

• cloned document may be removed by invoking ewsDocumentRemove () . All 

• clones created from documents in an archive must be removed before the 
« archive can be removed. 



• ewsDocumentCione 

• Clone an existing document under a new url in the database. 

• baseurl - URL of existing document 

• newurl • URL of new cloned document 

• handle • application-specific handle available in request context 
« 

• Returns document descriptor or EWS_DOCUMENT_NULL on error . 
•/ 

extern EwsDocument ewsDocumentCione 

( const char • baseurl, const char • newurl, EwaDocumentHandle handle }; 

/• 

• ewsDocumentRemove 

• Remove a previously cloned document from the database. 

• document - document descriptor of previously cloned document. 

• Returns EWS STAT0S_OK on success, else error code (TBD) . 

extern EwsStacus ewsDocumentRemove ( EwsDocument document ) ; 
ttendif /• EW_C0NF'IG_OPTION_CL0NINa */ 

Sifdef EW CONFIG 0PTI01I_D0C0MEHT_DATA 
« ewsDocumentSata 

• Retrieve pointer co raw data and data size from URL in archive 

ti ij2l * url of document 

bytesp ■ output: size of document Cas*is in archive) in bytes 

• datapp • output: pointer to start of document 
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• Returns EWS STATUS__OK on success, else eixor code (TBD) . 
•/ 

extern EvrsStatus ews&ocumentCata < const char * uil 

.uint32 *bytesp 
, const uintB **datapp ); 

ttendif /* EH_C0NnG_OPTI0N_DOCUMENT_I!!ATA */ 

Hifdef EW_CONFIG_OPTI0N_DOCUMENT_SET_REALM 

ftifdef EW~CONFIG_OPTION_AUTH 

/* 

* evsDocumencSeCRealm 

« Set ox change authentication realm of document at run -time. 

* 

♦ uil • uil of document 

• lealp - name of authentication realm, or NULL (or ♦•") to disable. 



* Returns EWS_STATUS OK on success, else error code, 

extern EwsStatus ewsDocumentSetRealm (. const char • url, const char •lealrn ) ; 

ftendif /• EW_CONriG_OPTION_AUTH */ 

(tendif /• EW_COHFIg]]^OPTIOn3dOCUME1^T_SET_REALM •/ 

#endif /• EVfS DOC H •/ 



A-2.6. src/include/ews„auth.h 

This file contains the definitions and prototypes of the authorization and security functions 
of the appiication interface. 



CONnDEHTIAL AND PROPRIETARY INFORMATION OF AGRANAT SYSTEMS, INC. 
THE EMWEB SOrTWARE ARCHITECTURE IS PATENT PEiTOlKG. 
EMWEB IS A TRADEMARK OF AGRANAT SYSTEMS. INC. 

Copyright (C) 1996, 1997 Agianat Systems, Inc. 
All Rights Reserved 

Agranat Systems, Inc. 
1345 Main Street 
MalCham, MA 02154 

(617} B93-786B 

salesaagxana t . com , suppox tsagrana t . com 
http : / /WW . agranat . com/ 

EmWeb /Server application interface to authorization database 



/ 



ews auth.h.v I.IB 1997/05/21 2l!SS:44 ian Exp 



Produce : 
Release: 



EmWeb 
R2 1 
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#iCndef _ews_auth_h_ 
ftdefine _EWS~AUTH~H~ 

»ifdef EW_CONF:iC_OPTIOK_Atn'H 

^include -ew_^types .h" 
(finclude "cw config.h" 



HTTP Authoiizacion cechniques are discussed in che HTTP specifications 
Knowledge of these principles are essential fox coxiect use of these ; 
authoiization interfaces. 



One or more HTML documents can be assocated with a single "realnf . A roalm 
is a case- sensitive ascii string that defines a "protection space" for zhe 
associated document(s). 

Each realm can have zero or more authentication entries associated with it. 
Xf a realm has no authentication entries, then it is considered 
"unprotected" by che server, and its acess will always be granted to any 
requesting client . 

For Chose realms with authentication entries, any client that attempts co 
access any document associated with that realm will be required to 
authenticate itself. To authenticate, the client must send authentication 
parameters that validate against at least one auchencication entry for that 
document's realm. Clients that do not authenticate axe not served the 
requested document. 

For example, assume a realm exists called "too". It has three 
authentication entries associated -with it (2 using che "basic" scheme 
defined in the HTTP specification, and one other ficticious type) : 

REALM: "foo" 

Authentication Entry 1: 
Type: "basic" 

parameters: Username""useri" 
Password' "guest" 
EwaAuthHandle : <application*s entryl idencifier> 



Authentication Entry 2: 
Type: "fucuie" 
paiameteis : index"37 

cooJcie-'BSTiBUg" 
. token- "537" 

EwaAuthHandle: (application' s encry2 identifier> 

Authentication Entry 3i 
Type: "basic" 

parameters: Usexname- "Sinclair" 
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* Password" "babylon" 

* EwaAuthHandie: <application*s en try 3 idencifier> 
• 

* Vhen a client attempts to access a document associated with zealm *'foo", ic 
vill need to authenticate against one of the above entries. Which one the 

* client authenticates against is at its disgtession. 
• 

* When a client does authenticate against one of the above entries, the 
« EVaAuthKandle fox that entry is stored in the current context fox the 
-* document (EwsContext) . The datatype of this EwaAuthHandie is 

* implementation -defined. 



/* • — — - o 

* Types & Constants 

- • — " •/ 

/• 

* Defines the authorization schemes supported by the EmWeb server. 

* Mew schemes will be added as they aie supported. 
•/ 

typedef enum 
{ 

If ifdef EW_C0NriG_0PT10N_AUTH_BASIC 

ews Au th s ch emeBa sic, 
« endif /• EW_COHFIG_OPTION_AUTH_BASIC •/ 

ft ifdef EW_CONFIG_OPTION_AUTH_DIGEST 

evsAuthSchemeSigest , 
« endif /• EW_CONriG_OPT10H_AUTH_DICEST •/ 

tf ifdef EW_^C0NFIG_0PTI0N_AUTH_M3ASIC 
ewsAuthSchemeManualBasic, 
endif /• EW_CONFIG_OPTIOH_AUTH_MBASIC */ 

U ifdef EM_CONFIG__OPTION_AUTH_MDIGEST 

ewsAuthSchemeManualDigest. 
tt endif /• ZW_CONFIG_OPTION_AUTH_MDICEST •/ 

ewsAuthMaxScheme /• count of supported schemes •/ 

} EwsAuthScheme; 



* this structure defines parameters for all the supported 

* authorization types. New parameters vill be added in 

* to this structure in the future 
•/ 

typedef union 
{ 

#i£def EW_C0NFIG_OPTI0N_AUTH_BASIC 
Struct 
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{ 

char •useiName; 
char •password; 
} basic; 

# end if /• EW_CONFIG_OPTION_AUTH_BASIC •/ 

# i f def i ned tEW_CONFIG_OPTION_AUTH_DIGEST) | 1 

def i ned ( EW_CONFIG_OPTI ON_AUTH_MDI GEST » 

scrucc 

{ 

char *U5erNatne; 
char *passWord; 

tt if def EW_CONFIG_OPTION_AUTH_DIGEST_M 

boolean digesCRequired; /" require client message daca verificacicn */ 
tt endif /• EW_CONFIG__0PTI0N_ACrrH_DIGEST_M */ 

) digest; 

ftendif /• EW_COHPIG_OPTION_AUTH_DIGEST II EW_CONFIG_OPTION_AUTH_MDIGEST •/ 

char leservedl; 
} EwsAuchParameters; 



* This struccme represents a single authorization entry. 
•/ 

cypedef struct 
I 

EvsAuthScheme scheme; 
EwsAuthParameteis params; 

EwaAuchHandle handle; /• user defined »/ 

} EwsAuthorizacion; 



/. — 

• Interfaces 

- - - / 



* evsAuthRegistei 

* And a new authorization entry to the realm. 
* 

* realm - Input, case sensitive asciiz realm name. 

* authorization - Input, buffer containing authorization entry information . 

* This buffer is free for use by the caller on retain. 
« 

* Returns a non-KULL handle to the authorization entry, or NULL on failure. 

extern EwsAuthHandle ewsAuthRegister 

( const char -realm, const EwsAuthorization -authorization ); 
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• owsAuthRemove 

• Deletes a particular authentication entry identified by handle. 

• handle • input, The handle that was returned by ewsAuthRegister 0 for 

• this entry. 
• 

• "He turns EWS_STATUS_OK on success, else failure code, 
extern EwsScatus evsAuthRenove ( EwsAuthHandle handle ) ; 

/• 

• evsAuthRealsiEnable 

• Enables a realm to restrict access to documents (restricted by default) 

• realm - Input, the realn to restrict 

• Returns EWS_STATUS_OK on success, else failure code 
*/ 

extern EwsStatus ewsAuthRealmEnable ( const chai ' realm ) ; 
/• 

• evsAuthRealmDisable 

• Disables a realm causing documents in that realn to be generally accessible. 

• realm • Input, the realm to restrict 
• 

• Returns EWS_STATUS_OK on success, else failure code 
extern EwsStatus ewsAuthRealmDisable ( const char realm ) ; 
/* 

• ewaAuthRealmOualifier 

• Returns realm qualifier string to append to realm names, or NULL 
*/ 

ftifndef ewaAuthRealmOualif ier 

extern const char *ewaAuthRealmOualifiei ( void ) ; 
#endif /• ewaAuthRealmpualifier •/ 

«if defined (EW CONFIG_OPTION_AUTH_DIGEST) \ 
I 1 defined (EW"C0KFIG~0PTI0N__AUTH_MDIGEST) 

/• 

• ewaAuchNonceCreate 

• Create raw input used to generate one-time authentication challenges 

• given a request context and realm. 
* 

■* context ■ request context 

• realm • null • terminated string containing name of realm 

• noncep • pointer to application- specific nonce parameters 

• No return value 
•/ 

extern void ewaAuthHonceCreate 

( EwsContext context, const char * realm. EwaAuthNonce -noncep ); 
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/• 

* svaAuchNonceCheck 

* validace that the pieviously created nonce is valid given the current 

* zeguesc. 
• 

« context - request context 

* realm •null-terminated string containing name of realm 
« noncep - pointer to requested nonce parameters 

* count - previous use count (0, l, ,,.) of nonce value 

* Returns ewaAuthWonceOK on success, ewaAuthNonceStale if valid but expired, 

* or evaAuthUonceDenied if nonce is not permitted given the request context 
•/ 

typedef enum EwaAuchiionceScatu9_e 
{ 

ewaAuthWonceOK, /• nonce value valid for request •/ 
ewaAuthNonceLastOK, /■ nonce value valid, but won't be again */ 
ewaAuthNonceStale, /■ nonce value is scale, generate new nonce ♦/ 
cvaAuchNonceDenied /• nonce value is invalid */ 
] EwaAu thNonceS ta tus ; 

extern EwaAuthKonceScacus evaAuthWonceCheck 

( EwsContext context, const char realm, EwaAuthNonce 'noncep, uincf count ); 
fiend if /• EW_C0NriG_OPTI0N_AUTH_{M) DIGEST •/ 

«ifdef EW CONFIG OPTI0N_AUTH MBASIC 
/' " " 

e vaAu thChecKBa sic 

Given the current context, realm, base64 cookie, and optionally 
decoded username/password text, determine if the authorization should 
be granted or denied. 

context - (input) request context 

realm • (input) null • terminated string containing name of realm 
basicCookie - (input) the base64 encoding of the text user ipassword, 

as described in the HTTP RFC. 
useiNatne - (input) if EW_CONFIC_OPTION_AUTH_MBASIC_DECODE is defined, 
then this parameter points to a null terminated string 
containing the user name decoded from the basicCookie. If 
Ew_cONFIG_OPTION_AUTH_MBASiC_DECODE is not defined, this 
is a NULL pointer, 
password - (input) if EW_C0NF1G_0PTI0N_AUTH_MBASIC_DEC0DE is defined, 
Chen this parameter points to a null terminated string 
containing the password decoded from the basicCookie. If 
EW_CONFIG_omOH_AUTH_MBASIC_DECODE is not defined, this 
. is a NULL pointer . 

Return value: boolean, if TRUE, then the authorization is granted and 
Che document is served, otherwise, authorization is denied. 

This function can be supended by ewsSuspend () . It's return values 
are ignored, and it will be recalled with the same paramecers when 
the context is resumed using ewsResumeO. 
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*/ 

ftlfndef ewaAuthCheckBasic 

excern boolean ewaAuthCheckBasic { EwsConCexc concexc 

, const char ^realn 
, coast char •basicCookie 
, coast cbai ♦userName 
, coast char ♦passwoid ); 

#endif /*• ewaAuthCheckBasic •/ 

tteniii /* EW_C0NFIC_0PTI0N_AUTH_MBAS1C */ 



«ifdef EW_CONriG OPTION__AUTH_MDIGEST 
evaAuthCheckDiges t 

Given the cuiienc context, lealm, usexname, and nonce, 
jecurn the coiiesponding MD5 hash of the username : realmipasswoid 
text. This text will be used by the seiver to verify the 
Buthoiization atcempt by Che client. 

context ' Cinput) lequest context 

realm • (input) null • terminated, string containing name of realm 

taken from the request header . 
nonce * (input) null- terminated string containing the nonce that 

was supplied to the server. 
usexName - (input) this parameter points to a null terminated string 
containing the user name as supplied in the authorization 
request header. 

digest • (output) on return, 'digest will point to a null -terminated 
ascii text string representing the MD5 checksum of the 
username, lealm and password (KD5 ( username :realm:password] ] 
as described in the Digest Access Authentication RFC2069 

Return value: boolean, if TRUE, then 'digest points to a valid KD5 hash of 
username: realm: password, which will be used by the server to complete 
the authorization process (which may or may not be granted) . If FALSE, 
the authorization is immediately denied. 

This function can be supcnded by ewsSuspendO . It's return values 
are ignored, and it will be recalled with the same parameters when 
the context is resumed using ewsResumeC). 

/ 

Itifndef ewaAuthcheckDigest 

extern boolean ewaAuthcheckDigest ( EwsContext context 

.const char 'realm 
, const EwaAuthNonce *noncep 
, const char "userName 
, const char "digest ); 

(tendif /• ewaAuthcheckDigest •/ 

»endif /• EW CONFIG OPTION_AUTH_MDICEST •/ 



Itifdef EW CONFIG OPTION_AUTH_VERiry 
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ewfiAuthveiifysecuiicy 

called a£tei_ the server has determined that the authoiization 
will be^granted fox the zequesc, this function allows the application 
to "shozt cizcuit" Che authoiization based on infozmation about 
the request (eg« IP addzess of client, etc). The method used 
to deteimine vhechez ox not the zequest is authorized is pzopxietazy 
CO the application. 

context - (input) zequest context 

realm - (input) null- terminated scxing containing name of realm 
taken from the request header. 

Return value: boolean, if TRUE, then the authorization is granted, and 
the document will be served to the client. If FALSE, 
the authorization is immediately denied. 

This function can be supended by ewssuspendl) . It's return values 
are ignored,- and it will bo recalled with the same parameters when 
the context is resumed using ewsResumeO . 

/ 

«ifndef evaAuthVerifySecurity 

extern boolean ewaAuthVezifySecuzity ( EwsConcext context 

.const char *realai ); 

«ehdif /• ewaAuthVerifySecurity •/ 
#endi£ /" EW_CONFIG_0PTI01J_AUTH_VERIFY •/ 



Local Variables: 
mode: c 
«•* tab-width: 4 
End: 

•/ 

«endif /' EW_C0HFIG__OPTI0N_AUTH •/ 
#endif /• _EWS_AUTH_H_ •/ 



A-2.7. src/indude/ews.ctxth 

This file contains definitions sind prototypes of the request context access functions of the 
application interface. 

• ©ws_CtXt.h,v 1.14 1997/05/25 23:30:32 giustl Exp 
• 

• Product t EmWeb 

• Release: R2_l 

• COMFIDENTIAL AND PROPRIETARY INFORMATION OF AGRAIIAT SYSTEMS, INC. 
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THE EMWEB SOFTWARE ARCHITECTURE IS PATENT PENDING. 
EMWEB IS A TRADEMARK OF AGRANAT SYSTEMS, INC, 

Copyright (C) 1996, 1997 Agianat Systems, Inc. 
All Rights Reserved 

Agianat Systems, inc. 
1345 Main Street 
Waltham, MA 02154 

(617) 893-7868 

saleseagiana t . com; suppor tOagranat . com 
http ; //www . ogxana t . com/ 
EmWeb/Servei public definitions 

'/ 

Wifndef _EWS_COHTEXT_H 
ltdefine ~EWS_CONTEXT_H 

ttinclude "ev_types .h" 
^include -ew^^config.h" 
ttinclude "ews_de£.h" 

/• 

• REQUEST COl-TTEXT 

« 

• Each HTTP request received by EmWeb/Seivei is assigned a unique context. 
' The context structure contains all the information pertaining to the 

' request, as well as internal state information regarding the processing 

• state of the request. 

• API functions are provided to give the application some visibility into 

• the current context state. 
•/ 

/* 

• ewsContextNetHandle 

• Return the application- specif ic network handle provided to EmWeb/Servei 

• by the application in evsNetHTTPStart 0 . 
*/ 

EwaNetBandle ewsContextNetHandle ( EvsContext context ) ; 

*tif defined <EW cONriG_OPTION_DEMA2ro_LOADlNG) \ 
1 1 defined Tew_config_option_cloming) 

« evsContextDocumencUandle 

• Return the application- specif ic document handle provided, to EmWeb/Seiver 

• by the application in ewsDocumentRegister 0 or ewsDocumentclone ( ) . 

• / 

EwaDocumentHandle evsContextOocumentHandle ( EvsContext context ) ; 
#endif /• Eh^CONnG_OPTION_DEMAND_LOADIKG H EK^CONFI G_OPTION_CLOHING */ 
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Sifdef EW_C0NFIG_OPTI0N_AUTH 

/• ~ 

* ewsConcexCAuchHandle 

* Return Che applicaci on -specific authorization handle provided to 

* EmWeb/5ervei by the application in evsAuthRegistei () . 
•/ 

EwaAuthHandle evsConcextAuthHandle ( Ews context context ) ; 
#endif /* EW_C0NF1G_0PTI0N_AUTH •/ 

#ifdef EW_COHriG OPTI0N_SCHED_SUSP RES 
/, " 

* ewsContextlsResuming 

* Return TRUE if EmWeb/Servei is resuming (as a result of ewsResumeO ) after 

* the context was suspended (as a result of evsSuspendO } . 
•/ 

boolean ewsContextlsResuming ( EwsConcext context } ; 
#endif /• EW_CONFIC_OPTION_SCHED_SUSP_RES •/ 

#if defined {EW_C0N7IG_0PTI0N_STRING) )| defined tEW_C0NFIG_OPTI0K_INCLUDEi 

* ewsContextlterations 

* Returns the iteration count corresponding for EMWEB_ITERATE 
*/ 

uint32 ewsContextlterations ( EwsContext context ) ; 

«endif /• EW_CONriG_OPTION_STRING I I EW_CONriG_0?TION_INCLUDE •/ 

#ifdef EW_CONFIG_OPTION_CONTEXT_SEHD_REPLY 
/• 

* ewsConccxtSendReply 

* Serves specified local path URL to browser in response to foitn submission 

* or raw CGI . 

EwsStatus ewsContextSendReply ( EwsContext context, char " url ); 
«endif /" EW_C0NFIG_0PT10N_C0NTEXT_SEND_REPLy •/ 

#if defined { EW_CONFIG_OPTION_FILE_GET ) \ 
II defined ( Ew2cONFIG_OPTION~FILE_PUT ) \ 
II defined ( EW_C0NFIG_0PTI0N_FILE_D2LETE ) 
EwsStatus ew5ContcxtSecFile( EwsContext context 

,£wsFileParains? paratns 
} ; 

Hendif /• EW CONFIG_OPTIOH_FILE_xxx •/ 



• The following' functions extract the corresponding fields from the KTTP/l.O 

• request header, if present, into an application-provided buffer. Each of 

• these functions return the number of bytes in the actual header value, even 

• if this is larger than Che application-provided buffer (though EmWeb/Server 

• will not overwrite the applicatoin buffer by honoring the buffer length) . 

• If the header is not present, zero is returned. The application may 

• specify a zero- length buffer in order to determine the size of the header 

• value. The returned value begins with the first non-whi tespace following 

• the HTTP header and ends just before the terminating end-of-line 
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chaxacter (s) . 

•/ 

ttifdef EW_CONFIG_OPTION_CONTEXT_DATE 

uintf ewsConcextBate { EwsConcext context, char *datap, uintf length ) ; 
<»endif /• EW_COKriC_OPTION_CONTEXT_DATE •/ 
#ifdef EW_CONF3G_OPTI0N_C0NTEXT_PRAGMA 

uintf ewsContextPxagira ( EwsContext context, char *datap, , uintf length ); 
#endif /• EW_CONFIG_OPTION_COHTEXT_PRAGMA •/ 

(fifdef ew_confic_option_co3jtext_from 

uintf ewsContextFioni { EwsContext context, char * da cap, uintf length ) ; 

«endif /* EW C0NFIG_0PTI0N_C0im:XT_FROM •/ 

fti f def EW_C0NFIG_OPTI0N_C0NTEXT_IF_MODIFIED_SINCE 

uintf ©vsContextifModifiedSince 

( EwsContext context, char 'datap, uintf length ); 
ttendif /• ew_config_option_context_if_modified_since */ 
#ifdef ew_config_option_coktext_referer 

uintf ewsContextKefeier { EwsContext context, char 'datap, uintf length ); 
#endif /• ew_config_option_context_referer •/ 

ffifdef EW_C0HFIC_OPT30N_COHTEXT_USER_AGENT 

uintf ews con textus ex Agent ( EwsContext context, char 'dacap, uintf length ); 
#endif /• EW_CONnc_OPTION_CONTEXT_USER_AGENT •/ 
#ifdef EW^CONFIC_OPTION_C0NTEXT_H0ST. 

uintf ewsContextHost ( EwsContext context, char * da tap, uintf length ) ; 
#endif /• EW_C0NFIG_OPTION_CONTEXT_HOST */ 

#endif /• _EWS_C017TEXT_H •/ 

A-2.8. src/include/ews_cgi.h 

This file contains the definitions and prototypes of the raw CGI functions of the application 
interface. 



ews_cgi.h,V 1,22 1997/03/29 17:50:49 ian Exp 

Product: EcnWeb 
Release: R2_l 

CONFIDENTIAL AND PROPRIETARY INFORMATION OF AGRANAT SYSTEMS, INC. 
THE EMWEB SOFTWARE ARCHITECTORE IS PATENT PENDING. 
EMWEB IS A TRADEMARK OF AGRANAT SYSTEMS, INC. 

Copyright (C) 1996* 1997 Agxanat systems, Inc. 
All Rights Reserved 

Agranat Systems, Inc. 
1345 Main Street 
Walcham, MA 021S4 

(617) B93-7B6B 

saleslagrana t . com , suppor t®agxa t . com 



/ 
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* hct;p;//vw, agranat.com/ 

« EmWeb/Sexvei application interface to raw CGI 
« 

V 

itifndef _EWS_CGI_H 
#def ine 2ews_cgi_H 

ftiaclude '•ew_cypes .h" 

* CGI INTERFACE 

* BoiWeb supports a raw CGI interface for imagemap and various special 

* application-defined CGI capabilities. 
« 

* The EmWeb/cocnpiler creates CGI URLs from specifications provided in 

* _ACCESS files. The application provides two functions for each CGI URL. 

* rixst, there is the CGI start function. This is invoiced by the 

* EmWeb/Servez to mark the start of a new CGI request. Second, there is the 

* CGI data function. This is invoked by the EmWeb/Seiver one ox more times 

* to pass network buffers containing raw CGI request data to the application. 

* The end of request data is indicated by an EWA_NET_BUFr'ER_NULL EwaNetBuf f er . 
« 

* The CGI application uses the ewsCGIDataO function to transmit response data 

* to the network. 

• / 

* evaCGIStart 
« 

* This per -CGI function is provided by the application. It is invoked by 

* EmWeb/servei at the start of a new request to the corresponding CGI UHt. 

* The application may return an application -specific handle. 

* context • context of cuiient request 

■* Returns application- specific handle to be used by EmWeb /server in 

* subsequent calls to evaCGIData. 
•/ 

typedef EwaCGIHandle EwaCGIStart_f { EwsContext context ) ; 
/' 

* ewaCGIData 
« 

* This per ; CGI ' function is provided by the application. It is invoked by 

* EmWeb/Servei zero or more times to pass raw CGI request data to the 

* application. 
* 

* cgi handle - application -specific handle as defined by ewaCGIStart 

* buffer • application buffer containing all or part of the row CGI 

* request data 
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• Ko letuxn value 

cypedef void EwaCGIData_f ( EwaCGIHandle cgi_handle, EvaNetBulf ei buff ei ) ; 
tfifdef EW_CONFIG_OPTION_CGI 

ews CG I S ends ta cu s 

This optional call causes the Emweb/Seiver to construct and send an 
appjopiiate HTTP status headei <and possibly ochei sexyei -generated 
headers) . It must be followed by one or more calls to ewsCGIDetaO to send 
additional headei infoimation and optional body content. (Mote chat a call 
to evsCGIDataO must not precede the invocation of this function). 

Note: If the application desires complete control of the response* it may 
simply send all header information itself using evsCGIDatoO instead of 
invoking this function. 

context - context of request 

status ■ 3 'digit status code followed by reason string 

string * string containing additional headers and/oi data, or KUlL 

Returns EWS_STATUS_OK on success, else error code ITBD) . 

'/ 

extern EwsStatus ev s CGI Sends tatus 

( EwsContext context, const char • status, const chai • string ); 



• evsCGIData 

• This function is called by a raw CCl application one oi more times to send 

• lav CGI response data to the biovsei client. The application is responsible 

• for throttling its use of the CPU. Note that response data may include raw 

• HTTP headers as veil as data, Theiefoie, a CR-NL sequence must be 

• transmitted to properly delimit the headei portion of the response fior. 

• any returned data. 

• Note that evsCGISendStatuE 0 may be called once befoie any calls to 

• ewsCGlDataO to generate standard HTTP headers. Otherwise, the application 
ntust geneiate all standard headers itself. 

• Note that sending a EWA_NET_BUFFER_NULL terminates the request. 

• context . • context of request 

■* buffer • buffer containing data to send, or Ewa_NET_BUFFEB_NULL 

« if this is the last buffer in the response. 

• No return value 

extern EwsStatus evsCGIData ( EwsContext context, EwaNetBuf f ei buffer J; 



* evsCGIRedirect 

* This call causes the En«eb/Servei to respond to the browser with the 
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* document specified by che URL (if local), or with a redirect (if not). 

* This funccion will ceiminace che request. Noce chac this feature can not 
« be used in conjunction with evsCGIDaca(} or ewsCGIStatus{) . 

• 

* context • context of request 

* url • URL for redirect 
* 

* Returns EWS_STATUS_OX on success, else error code (TBD) . 
*/ 

extern EwsStatus evsCGXRediiect { EvsContext context, const char *uil ); 



#i f def EW_CONFIG_OPTION_CGI_SERVER_SOrrWARE 
/* 

* evsCGIServeiSofcvaze 

* Returns a string corresponding to the server software such as 

* "Agranat'EinWeb/R2_l" 
'/ 

extern const chai •ewsCGI Server Software ( void ) ; 
«endif /• ew_config_option_cgi_server_software •/ 

#ifdef EW_CONFIG OPTION_CCI_CATEWAY_IKTERFACE 

* ewsCGIGatewaylnterface 
• 

* Returns a string corresponding to the CGI version "CGI/l.O" 
*/ 

extern const char ♦ewsCGIGatewaylnterface ( void ) ; 
«endif /• EW_C0NFIC_0PTI0N_CGI_GAT£WAY_IHTERFACE ♦/ 

ftifdef EW_C0NFIG option_cgi_server_protocol 

* ewsCGIServei Protocol 

« 

* context • context of request 

* datap * pointer to data buffer 

* length • size of data buffer (may be zero) 
* 

* Returns number of bytes in actual protocol string, or zero if not present. 
•/ 

extern uintf evsCGIServerPxotocol 

( BwsContext context, char -datap, uintf length ); 
#endi£ /• EW_CONFIG_OPTION_CGI_SERVER_PROTOCOL •/ 

#ifdef EW_CONFIG_OPTION CGI_RE0UEST_METHOD 

* ewsCGXReque»tHechod 
♦ 

* context - context of request 

* datap ■ pointer to data buffer 

* length • size of data buffer (may be zero) 
* 

* Returns number of bytes in actual request method, or zero if not present. 
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extern uintf evsCGlEequestMethod 

( EvsConcext concext, chai •datap, uintf length ); 
#endif /• ew_config_option_cgi_reouest__method •/ 

#ifdef EW_CONnG OPTION CGI_PATH_IKro 

* evaCGIPathZnfo 

* context - context of request 

* Returns pointer to Pathlnfo string, or NULL if not present 
V 

extern const char • ewsCGIPathInf o ( Ews Con text context ) ; 
*fendif /« EM;_C0NFIG_OPTI0N_CGI_PATH_INFO •/ 

»ifdef EW_COHriG_OFriOH CGI SCRIPT_NAME 

* evsCGISciiptName 

* context • context of request 

* Returns pointer to script name string 
•/ 

extern const char • ewsCGIScriptName* { EwsContext context ) ; 
(fendif /• EW_CONFIG_OPTION_CCI_SCRIPT_NAME •/ 

(tifdef EW_CONFIG_OPTION CGI OUERV_STRING 

* ewsCGlouerystring 
« 

* context * context of request 

* datap ' pointex to data buffer 

* length * size of data buffer (may be zero) 
« 

* Returns number of bytes in actual query string, or zero if not present. 
•/ 

extern uintf ewsCGIOueryString 

( EwsContext context, char *datap, uintf length ); 
#endif /• EW_CONFIG_OPTION_CCI_0UERY_STRrNG •/ 

Itifdef EW CONFIG OPTION CGI_CONTENT_TyPE 

* ewsCGIContentType 

* context • context of request 

* datap - pointer to data buffer 

* length • size of data buffer (may be zero) 
• 

* Returns number of bytes in actual content type, or zero if not present 
•/ 

extern uintf ewsCGIContentType 

( EwsContext context, char *datap, uintf length }; 
flendif /• EW_CONFIG OPTION CGI_CONTENT TYPE •/ 
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#i f def EW_CONFIG_OPTIOH_CCI_C0KTENT_LENGTH 
• ewsCGIConcenCLength 



« 



* concexc • concext ot request 
• 

* Recuins content length as specified by client, or zero if not present, 

* or EWS_CGI_CONTEKT LENGTH_CH0N1CED if chunked. 
•/ 

^define EWS_CGI_COHTENT_LENGTH_CiiUNKED Oxffffffff 
extern uint32 ewsCGI Con tent Length ( Ews Context context ) ; 
«endif /• EW_CONFIG_0PTI0N_CGI_CONTENT_LENGTH •/ 

Jtifdef EW_CONFIG_OPTION_CGI__CONTENT_ENCODING 

* evsCGIConcentEncoding 
• 

* context - context of request 

* datap ■ pointer co data buffer 

* length • sire of data buffer- (may be zero) 



• Returns number of bytes in actual content encoding, or zero if not present. 
•/ 

extern uintf ewsCGIContentEncoding 

{ EwsContext context, char "datap, uintf length ) ; 
#endif /' EW_CONFIG_OPTION_CGI_C0NTENT_ENCODIMG */ 

#endif /• EW_CONFIC_OPT20N_CGI •/ 

#endif /■ _EWS_CGI_H •/ 



« 
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^* $Id: ew_db.h,v 1.30 1997/06/28 11:59:50 ian Exp % 

• Product: EmWeb 

* Release: $Name: $ 

• %CopyRiyht% 

* EmWeb database definitions 
V 

Itifndef _EW_DB_H 
^define _EW_pB_H 

t include " ew_co(nBDon . h " 

^include "ew_types.h" 

^include ♦'ew_f orm.h" > 

Itinclude "evciniap.h" 

^include "ew5__def.h" 

^include "ews„cgi.h" 



• DOCUMENT ARCHIVE 
» 

• An EmWeb document archive contains two parts. These are the archive data 

• component and the archive object -component. 
* 

• The archive object component contains all the run- time object code 

• associated with an archive. A public symbol (determined by EmWeb/Compiler 

• on a per-archive basis) points to an archive descriptor (EwsArchive) . This 

• contains all of the linkage required by the Emweb/Server to access the 

• archive-specific run- time object code. 
• 

• The archive data component contains all the static data describing 

• individual documents in the archive. The data component is an endian- 

• independent fully relocatable contiguous block of constant data 

• analogous to a file. In fact, it could be a file. The data component 

• begins with an archive header and contains one or more documents. 



/• ' 

* Archive Descriptor 

* Each archive has a unique archive descriptor in the object component of the 

* archive. The archive descriptor is a list of functions called by the 

* EmWeb/Server to execute archive-epecif ic object code while processing 

* requests for documents in the archive. Unsupported functions (i.e. 

* features not selected when the EmWeb/Con^iLer was built) are represented 

* by a NULL pointer. 
•/ 

typedef const void EmWebString:_f ( Ewscontext context, uint32 index ) ; 
typedef const char * En»weblaclud€L^ ( EwsContext context, uint32 index ); 

/• Cookie Attribute structure, element of eiitweb_cookie_tbl [] */ 
typedef struct EwCoo)tieAttr_s I , 

char "name; 

char *path; 
) EwCoo}tieAttributes; 



typedef struct EmwebCGITable^s 
[ 

EwaCGIStart_f -startwi ; 
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EwftCGiDat«_£ *aata„f I 

} EinWcbCGITabie, •EroWebCGITableP; 

typedef struct ewsArchive_s 

^ uint32 magic; /• Magic number for archive validation •/ 

« define EW_ARCHIVEL.0BJECTJ4XGIC ( ( ' E' «24 ) | ( ' W «16 ) | ( ' O' «8) j 'b' ) 

uinte versionjnaj; /* Archive version {major/minor) */ 

■uintS versioivjnin; 



M define EWL-ARCHXVe_VERSIOl?_MAJ 1 
It define EW^CHlVE_VERSION_MIN 1 



uintB compilerjnaj; /* EroWeb/ Compiler version (major/minor) •/ 

uintB conipiler_;ain; 

define ew_ARCHIVE_DATEL.11 2 3„SI2E 32 

char date_1123[EW_^CHIVELJ)ATE;_1123_SIZEj: /' creation date •/ 

Archive-specific <EMWEB_STRING> dispatch function. Takes context 

* and index arguments. Index selects the C-code fraiyinent corresponding 

• to an instance of <EMWEB_STRING> . 

Emwebstring_f •emweb_string; 

^* Archive-specific <emweb_INCLUDE> dispatch function. Takes context 
. and index arguments. Index selects the C-code fragment corresponding 

♦ to an instance of <EMWEB_include> . 

EmWebInclude_f •emweb_include; 

^' Archive-specific form table. The Form node index is hierarchical and 

• contains a form number and an element number. The form table is 

• indexed by form number (0..n-l) . Each form table entry contains a 
- pSinter to an array of field elements indexed by one less than the 
. element number. (An element number of zero starts the fom and 

* an element number greater than the number of elements in the form 

* the form)! The table contains all the necessary information to 

. se^e and ISmit forms. The emweb_forTLenu:iL.table is a list of strings 

• corresponding to RADIO and single select values. 

• / 

const BwFormEntry *emweb„£orrtt.table; 
uint32 emweb_for7iutable_si2e; 
const char **emweb„f oniL.enunutable; 
uint32 emweb_form_enuiiutable^ize; 

^^ Archive-specific imagemap table. T^lTll^ 

* compiled by the Emweb/Compiler into the archive. This table le 

• indexed by a document node corresponding to the mapfile. The 

. t^Jfent^y contains a table of rectangular regions which are scanned 
« for matching x.y coordinates to find a match. 

♦ / 

const EwlmageMapTable *emweb_image_table; 
uint32 emweb_image^table_si2e; 

^* Archive-specific CGI action dispatch table. 
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const EmWebCGlTable *einweb_cgi_tablej 
uint32 einwab_cffi„table_size; 

• Reference count - this is initialized to zero by the Emweb/ Compiler, 

• but is writable (.data section). This value is incremented for each 

♦ cloned page It is also incremented for each page currently in use by an 

* uncompleted request. This prevents the application from attempting to 
« remove an archive that is in use. 

•/ 

yint32 referenceucount; 

^* Document list - this is the anchor of a list of loaded documents and 

* is used exclusively by Emweb /Server to Xeep tracJt of per-document nodes 

* created when loading the archive into the open hashed file system. 

• This should be set to EWS_DOCUMENT_NULL by the EmWcb/Con«)iler. 

•/ 

EwsDocument document_list; 



• Archive-specific cookie table. This table is indexed by data_offset 

• value find in the cookie header node. 



J 1 'NOTE: location of this variable is important. For bacward comatibility 
of archives, it KUST be the last field in this structure. 



const EwCookieAttributes •emweb_coo)cie_tbl; 



) EwsArchive_t; 



DOCUMEHT ARCHIVE DATA COMPONENT 

The document archive data component is a relocatable, endian-independent, 
static data structure containing compressed documents and information about 
how to access them. 

All 16-bit and 32-bit quantities are represented as arrays of octets. The 
first octet is the most significant Ci.e. Big Endian) . 

All pointers are 32-bit (array of four octets) offsets from the beginning of 
the archive data. 

All strings are .asciiz CNO'-teminated ASCII) and are represented by a 
pointer to the string. 

Data storage for strings and various other variable-length components can 
be placed between headers at the discretion of the Emweb/compiler, 

The document archive date component takes the following form: 
BwsArchiveHeader 

(optional padding) j^.. > . 

t EwsDocumentHeader { EwsDocumentNode, ... J (optional padding) J, ... 

The optional padding can be used to store variable length fields such 
as strings, compressed documents, etc. 

/ 

EwsArchiveHeader 

The archive data component begins with an archive header at offset zero 
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• KOTE WELL; KEEP SI2E0F_EWS.^CHIVE_HEADER UP TO DATEl I I 
typedef struct EwsArchiveHeaaer_s 



I 



# 



uint8 



magic [4] ; 



/* Magic nurnbcr for archive validation •/ 



define EW_/lRCHIVE_MAGIC_0 
define EW_^CKXV^LMAGiq_l 
define EW_>RCHIVELXAGICL,2 
define EVUUICHTVE_MXCIC_3 
define EW_^CHIVE_^GIC 



'E' 

•d' 
'a' 



uint8 
uinte 

uint8 
uint8 

uintB 
uintB 
uintB 
uintB 
UintB 
UintB 



versioiuJi^j : 
versionjnin: 

compiler_jnaj ; 
compiler_jmin; 



( ('E'«24) I ('W'«16) I (•d'«e) I'a' ) 
/* Archive version (major /minor) */ 

/• Eroweb/compiler version (major /minor) */ 



lengtht4]; /• length of archive, octets •/ 

name_of f set U] ; /• Offset to archive name string •/ 
date_ll23_offset(4] ; /• Offset to HTTP date (RrC1123 format) 
date_1036_off set 14] ; /• Offset to HTTP date (RFC1036 format) 
doc_of f set 14] ; /• Offset to first document header •/ 
dict_off set 14) ; /• Offset to compression dictionary •/ 



J EwsArchiveHeader, • EwsAr chive Header P; 
((define SI2E0F_EWS_ARCHIVE_HEADER 32 /• NEVER use sizeof {) •/ 



EwsDocumentKeader 

For each document in the archive, there is a corresponding document 
header. The first document header is referenced by the doc_offset 
field of the archive header, subsequent documents are chained together 
using the next_offset field in each document header. The last document 
header in the archive contains a zero in the next.offset field. 

The following types of documents are supported: 



LinX 



Hime 



Text 



Index 



Form 



Generates a redirection URL. The redirection URL is an 
uncompressed string stored in the data area. node_count 
should be zero. 

Generic (non-text) mime type. The data area contains the mime 
document. The mime content is indicated by the string at 
mime_off8et. Compression is optional. node_count should be 
zero. 

Generic text type. The text may contain EmWeb/Compiler 
HTML extensions for <EMWEB_STRING> , <EMWEB_INCLUDE> , 

form get processing, etc. Each such extension results :.n 
one or more document nodes being present describing the 
actions to take at certain points during the processing of 
the data. The data contains the static parts of the 
document and may optionally be compressed. The mime content 
is indicated by the string at mime_offset. 

An index URL. An absolute path URL is stored as an 
uncompressed string in the data area. node_count should be 
zero. 

• A form action URL. There should not.be a data section. 
There will be a FORM node that indicates the index to 
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use for the start/set/submit operations in handling a 
posted form. 

- A CGI URL. There will be a CGI node that indicates the 
index to use for the start/data operations in handling a 
raw CGI request. An optional data section containing 
the uncompresBed content of the corresponding URL file 
(if present) is made available in the EwsContext. This 
could be used for CGI imagemap data, for example. 

- A mapf ile URL. There will be an imagemap node that 
Indicates the index into a per-archive imagemap table 
for processing an imagemap. 



Note that any document might be narXed hidden. If so, the document is 
not accessible by a client browser directly, instead, the document is 
used as a building block. It can be cloned, or EMWEB_INCLUDEd. 

NOTE WELL: KEEP SIZE0F_EWS_POCUMENT_HEADER UP TO DATE!! 
typedef struct EwsDocumentHeader^ 

next_o£fset{4j ; /* offset to next document or 0 if last •/ 
url_of f set 14} ; /• offset to URL string •/ 

document_type; /* type of document •/ 



uinte 
Uinta 

uint8 



/♦ If you odd a document type, update ../compil 
define EW_ARCHIVEJX)C_TYPE.J1ASK 
define EW^CHIVE_DOC_TyPE_LINK 
define EW_JiRCHIVEJ)0C_TypE_^4IME 
/ • EW_ARCHIVE_DOC_TYPE_TEXT 
define EW_JiRCHIVE_POC_TyPE_FORM 
define EW_^CHIVE_DOCL_TyPSL.INDEX 
define EW_ARCHIVE_POCL.TyPE_CGI 
define EW_ARCHIVE_DOCjrYPE_IMAGEMAP 
define EW_^CHIVE_DOC_TyPE_FILE 

define ew_^chive_do{:;_flac„static 
define ew_j^chive^OC_FLAG_FORM 

define EW_JlRCHIVE_J)OC_FLAG_HIDDEN 



OxOF 

0 

1 

2 

4 

5 

8 

9 

10 

0x20 
0x4 0 
0x80 



ler/readarchive.c •/ 
type field */ 
redirection URL •/ 
generic mime data type •/ 
[obsolete] •/ 
Form action URL */ 

/• index URL •/ 
CGI-BIN interface •/ 
Imagemap interface */ 
local filesystem •/ 
treat as static document '/ 
contains form node •/ 
hidden (internal use) •/ 



uintS 



comp_;nethod; /• compression method */ 



define EW_>RCHIVE_COMPRESSI01^_NONE 0 
define ew_aRCHIVE_C0MPRESSI01CEMWEB 1 

define EW_ARCHIVE;_COMPRESSIOriJ)EFAULT EW_;uiCHIVE„COMPRESSIOH_EMWEB 

number of document nodes */ 
offset to array of document nodes */ 



length of original (uncompressed) data •/ 
length of compressed data */ 
offset to compressed data */ 



uintS 


node_coiint [21 ; 


/* 


uint8 


node^off set [41 ; 


/' 


uinte 


mime_offset[4] ; 


/* 


UintB 


realm.Of f set [4] 


;/• 


uint8 


origL_length[4j j 


/* 


ulnt8 


dato_length[4] ; 


/• 


uinte 


dato^of f set [4] ; 


/• 


uint8 


hdr_node„count ; 


/• 


uintS 


hdr_flags; 


/* 



number of document header nodes */ 



define EW_JiRCHIVELJDOC_HDR^COOKIE_FLG 
define EW^CHIVE_DOC_KDR_CACHE_FLG 
define ewl;«chive_DOCUHDR^VARV_flg 



0x01 /* set if cookie hdr present 
0x02 /• set if CACHE hdr present * 
0x03 /• set if VARY hdr present •/ 



uintfi 



reserved 121 ; 
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) EwsDocumentHeader, * EwsDocumentHeaderP; 

adefine SI2E0F_ewsjD0C:ument_KEADER 40 /* never use sizeof */ 
ewsDocuroentNode 

The document header points to an array of zero or more document nodes 
followed by header nodes. 

The node_count field of the document header indicates the number of nodes 
present. Each node represents a special run-time action to be taken by the 
Emweb/Server when processing requests for the docxment. When processing 
reaches the specified point in the uncompressed data, the specified action 
is taXen. 

Header node contains information needed to create HTTP reply header (s). 
The hdr_count field of the document header indicates the number of hdr^nodes 
present. Each node represents a special run-time action to be taken by the 
Emweb/Server when processing requests for the document. Header nodes are processed 
first as the headers are built into the reply befor data part of the document 
is processed. 

Header nodes are sorted in the archive by type. Compiler sorts and includes 
in the archive only headers of the types for which the flag is set in hdr_flags 
fieltS in the Document Header. 

The document header node{s) immediately follow the ewsDocumentNodes for a 
given document . 

For a cache control header, the first offset in the node will be used to 
point to the ETAG for this (static) document, ETAGS are used for 
cache-control in HTTP 1.1, (Note that an ETAG will not be used for a 
dynamic document) . 

The type field will indicate what type of header node it is - cache or 
state cookie, etc. 
The other fields are reserved. 

Note that in the future, we may use the last 32 bits in this header 
to be an instance C pointer for the cache control header. 

NOTE WELL: KEEP SIZEOF_EWS_D0CUMENT_NODE UP TO DATE! ! ! 

/ 

typedef struct EwsDocumentNode_s 

•uintS data_of f set [C] ; /* location of node in uncompressed data 

stream (relative to start of uncompressed 
document data) , 

for COOKIE header it is an index to Cookiexable 



uintB 



type; 



/* type of node */ 



/• If you add a node type, update . ./compiler/readarchive.c •/ 



M define EW_pOCUMErrOlODE_TYPEL-STRING 

m define EW^OCUMENT_NODEL.TyPEu.INCLUDE 

# define EW_J>OCUMENT_J)ODEjm>^ORM 
M define EW_pOCOMENT_JJODEjnfPE„CGI 

« define EW_J30CUMENT_J30DE_TyPE_lMAGEMAP 

# define EVO)0CUMEIIT_N0DE_TyPEL_C00KIE 
« define EW^OCUMEHT_JflODEL.TyPEL.CACHE 

# define EW_P0CUMENT_j;0DE_TYPELVARY 



<EMWEB_STRING> •/ 
<EMWEB^HCLUDE> */ 
<FORM> Operation */ 
CGI operation •/ 
Image Map */ 

<EMWEB^CO0KIE> •/ 
CACHE •/ 

content negotiation*/ 



uintB 



attributes; 



/• node attributes •/ 



/• If you add a node attribute, update ../compiler/readarchive.c •/ 
define EW_j30CUMENT_;flODELJlEPEAT 0x01 /• repeat until NULL for 

EKWEB_STRING and 
aiWEB_INCLUDE nodes •/ 
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« define EWLDOCUMENT_JiDR_SECURE 0x02 /• SECURE flag for cooJcie */ 

uintS reservedl2]; /* reserved for future use •/ 

uintS index[41; /* index assigned to node. This may be 

hierarchical, (e.g. the FORM index 
contains a form number and element 
number, the STRIHG index contains 
a conversion type (most significant 
8 bits) and a string number (least 
significant 24 bits) . . 
The COOKIE index contains string number 
for coo)cie's value generating C-code. 
This index is applied to the switch contained 
in emweb„string() function •/ 

} £wsDocumentNode, * EwsDocumentModeP; 

♦define SIZE0F„EWS__D0CUMENT^0DE 12 /• never use sizeof */ 
♦define NEXT^OCNODE( x ) ( (EwsDocumenttJodeP) ( ( (uint8 •){x)) \ 

+ S I Z EOF_EWS_DOCUMENT_NODE ) ) 

♦endif /• _EW_DB_H •/ 
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• $Id: ew_form.h,v 1.23 1997/0fi/28 11:53:50 ian Exp $ 
« 

♦ Product: Ereweb 

* Release: fMame: $ 



* 



• %CopyRi9lit% 
♦ 

• Eaweb Forra definitions between server and generated code. These are 

• also used in typed oiweb.^RINGs , etc. 

«ifndef _EW^0RlOl 
♦define _EW_F0R>Oi 

♦include -ew_types .h" 
ttinclude •'ew_coinmon.h'* 

♦ include "ews^def.h" 

/• 

• toplication Poira Serve Function 

• Fills in form template with default values. {We comment out the prototype 

• to avoid compiler warnings the actual application functions define 

• a specific form structure instead of void*) . 
« 

• context - request context 

• form - pointer to f onn-specif ic structure 
• 

• Ko return value 
•/ 

♦ ifndef cplusplus 

typedef void EwaFormServe_f ( ) ; 

♦else /* cplusplus */ ^ . 

typedef void EwaFormServe_f ( EwsContext context, void • form ): 

Itendif /• cplusplus •/ 

/* 

• Application Form Submit Function 

• Processes submitted form. (We comment out the prototype 

• to avoid compiler warnings — the actual application functions define 

• a specific form structure instead of void*). 
-* 

. * context - request context 

• form - pointer to form-specific structure 

• Returns NULL for default response to server (accepted) , or redirection URL. 
•/ 

tifndef ^cplusplus 

typedef char * EwaFormSubmit_f ( ) ; 

ttelse /* cplusplus •/ . J. ^ , 

typedef chir • EwaFormSubmi t_f ( EwsContext context, void • form ); 

♦ endif /• ^cplusplus */ 

/* 

• field SJ^ent has a type associated with it. Each type has conversion 

• ^SStines to handle conversions between HTML and internal representations. 

• NOTE: i£ you modify this enum list, you MUST update the FieldMap in 

• file ewc_code.C!l 
•/ 

typedef enum EwFieldType-.e 

* cwFieldTypeDecimalOvcrride • 0 /• unsigned decimal integer V ' . 
ewFieldiypeRadio /' "'iio ^""n - serve setup and submit •/ 

ie^FierdWeRadioField /• radio fields - used in serving form 
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ewFieldTypeSelect 
, ewFieldTypeSelectField 
.ewFicldTypeSelectMulti 
, ewFieldTypeCheckbox 
. ewFieldTypeTaxt 
. ewFieldTypelmaae 
, ewFi e X dTypeDe c imalUin t 
, ewFieldTypeDecinallnt 
, ewFieldTypeHexInt 
,ewFieldTypeHexString 
, ewFieldtypcOottedIP 
, ewFieldTypelEEEMAC 
, ewFicldTypeFDDlMAC 
, ewFi e 1 dType S t dMAC 
, ewFieldTypeDecnetIV 
, ewFieldTypeFile 
, evFiel dTypeText Override 
.ewFieldTypeObjectID 
,ewFieldTypeMWC 
EwFicldType; 
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select enujti - serve setup and suTDmit */ 
select enun fields - .used in serving form •/ 
multiple select */ 
chec)cbox */ 
text field •/ 
image field •/ 
unsigned integer */ 
signed integer •/ 
hexadecimal integer */ 
hexadecimal string */ 
dotted IP address •/ 

IEEE MAC •/ 
FDDI MAC */ 
Standard MAC •/ 
Decnet IV Address ♦/ 
input type file handle •/ 
serve input file name field */ 
object identifier */ 
MUST BE LAST */ 



• Form Field Representation 

• The compiler generates the following structure for each element in the 

• form in general, a FORM document node is placed in the archive at the 

• offset immediately following a VALUE= in TEXT, TEXTAREA, HIDDEN, or PASSWORD 

• field. The field component of the form node index refers to a field 

• structure as defined below. The' field type would be ewFi el dTypeText, or 

• one of the derivative extended types such as ewFieldToDottedlP. If a 

• VALUE was specified in the source html, the compiler translates it into 

• the oppropriate internal representation and creates the def ault_value of 

• the field. (For ewFi el dTypeText, this is simply a pointer to the null 

• terminated string. For other fields, this is a pointer to a value whose 

• length is determined by the type in ewFieldToble) . The NAME-" part of 

• the field is saved, and the offset into the compiler-generated form for 

• the value and status portions of the field is stored in valuc_offset and 

• status„offset. 

• Checkboxes and multiple selections are fairly straight forward. 

• The type ewFieldChecXbox or ewFieldSelectMulti is used, and the 

• node appears where the word "CHECKED" or "SELECTED" may appear. If a 

• VALUE* is present, it is saved in the sel_value field. Otherwise, these 

• types are identical to the extended text types above. 

• Radio buttons and single-select boxes are more complex, with a single 

« NAME-, there may be multiple VALUE- where only one applies to the actual- 

• value of the form field. With N radio buttons or single select options, 

• the compiler generates N+1 field structures. One structure is used to 

.* read and write the value in the internal generated form. This would have 

• type ewFieldTypeRSdio or ewFieldTypeSelect, contain the default value, 

• offsets into the form structure, and the field name. In addition, an array of 

• integers containing all values corresponding to the generated enumerator is 

• soved in enunulist. The other N field structures. would represent each radio 

• button or select option and have the type ewFieldTypeRadioPield or 

• ewFieldTypeSelectField, These are referenced by form nodes in the document, 

• archive at the location corresponding to. where a "CHECKED- or "SELECTED" 

• keyword would be inserted. They would not have a name field. Instead, 

• the enum_value field would be set to the VALUE ^ enumeration corresponding 
« to the specific field. 

,/ 

typedef struct EwFormrield_5 

^ EwFieldType field_type; /• type of field ♦/ 

const void •default_value; /• pointer to default value •/ 

yijjtf value_off set; /• offset to value in form struct •/ 
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const char 
const int 
Int 

const char 
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status_of£set; 
*naine ; 
*enun\_list; 
enujiL-value; 
*sel_vftlue; 



} EwFomField, * EwFoimFieldP; 



/* offset to status in form struc: 

/* name of field from KAME="" •/ 

/* list of field values by eniun */ 

/• SELECT/RADIO value of field */ 

/• SELECT multiple value field •/ 



* Form Representation 

« The following structure represents an KTML FORM. This points to the 

• application-t>rovided serve and subndt functions, indicates the size 

* d£ the compiler-generated fozm structure* and points to a table of 

* field structures as defined above, 
*/ 

typedef struct EwFormEntry_s 

EwaFormServe_f •serve_f; /• application serve function ♦/ 

EwaFormSubmi tw^ •submit^f; /* application submit function •/ 

uintf fonrusize; /• sizeof form structure */ 

uintf f ield-count; /* number of fields in form •/ 

const EwFormField -field^list; /• list of fields •/ 
) EwFormEntry, * EwFormEntryP; 

/• 

• Document Node Conversion Macros 

* These macros convert between the J 2-bit node index and a form and element 

• index. 
•/ 

tdefine EWJ_rORM_El.EMENT_START 10) 
#define EW_F0RM_ELa4ENT_END (Oxffff) 
«define EW_FORM_NODE_INDEX_TO_FOR>LINDEX (i) Hi) » 16) 

*tde£ine EW_F0RfOI0DE„INDEX„T0_ELEMENT_lNDEX ( i ) ({i) 6 Oxffff) 
fdefine EW_rORKL-ELEMENT_TO_NODE_INDEX ( f , e) (((f) « 16) I (e) ) 

/• 

* Form conversion functions. 

* The "To" function converts to HTML ASCII format from the internal 

• representation and writes it directly to the output data stream, 

♦ The "From" function converts from HTML ASCII contained in a parsed netvfor)t 

• buffer EwsString and converts it to the internal representation. 
•/ 

typedef void EwFieldTypeTQ_f 

( EwsContext context, const EwFormField "field ) ; 
typedef void BwFieldTypeFron^_£ 

I Ewscontext context, const EwFormField *f ield, EwsStringP stringp ) ; 
typedef void EwFieldTypeFree_£ ( void •p ) ; 

«ifdcf EW_CONFIGL.OPTIO»?_TIELDTyPE_RADIO 

extern EwFieldTypeTo^f ewFieldToRadioField; 

«endif /• EW_C0NFIG„0PTl01CFIEl'I>TyPELJlADI0 •/ 

#if defined (EW_C0NFIG_OPTI0N_riELDTyPE_RADIO) \ 

1 1 defined (EVL-CONFIG_OPTIOR_nELDTyPELJSELECT„SINGLE) 
extern EwFieldTypeFronu-f ewFieldFroWRadio; 
«endif /• EVCC0NriG_OPTIOrL.FIELDTyPE_RADI0 1 SELECT_SINGLE */ 



tlfdef EW_C0NFlG_OPTI0N_FIELDTyPE_SELECT_SINGLE 
extern EwFieldTypeTo_f ewFieldToSelectField; 
«eadif /* EW_C0KFIC_OPTI0It.FIELDTyPE„SELECT_SINGLE •/ 

fiifdef EW_C0NFIG_0PTI0N_FIEL13TyPE_SELECT_WULTIPLE 

extern EwFieldTypeTcuf ewFieldToselectMulti ; 

extern EwFieldTypeFronuf ewFieldFromSelectMulti; 
#endif /• EW CONFIG_OPTIOlL.I*IELDTyPELSELECT^LTIPLE */ 
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*ti£def EW„CONriG_OPTI01^_FlEU)TyPEL_CHECKBOX 
extern EwFieldTypeTo_f ewFielcaToChec)tbox; 
extern EwrieldTypeFroin_f ewFieldFromChecWsox; 
Kendif /* EWLC0NFIG_0PTI0t?_FIEI'I>TyPE;_CHECKBOX •/ 

#i£def EW C0NFIGLOPTI0N_FIELDTyPELCHECKB0X 
extern EwFieldTypeTo_f ewFieldToText ; 

extern EwFieldTypeFronuf ewFieldPromText ; 

extern BwFieldTypeFree_£ ewFieldFreeText; 
Sendif /• EW_CONFIGL.0PTI0H_FIELDTYPE_CHECKB0X */ 

extern EwFieldTypeTo_f ewFieldToDecimalUint; 

(tifdef EW_CONFIG_OPTIOIUFIEU)TyPE_IMAGE 

extern EwFieldTypeFronuf ewFieldFromlmage; 

Itendif /• ew_config_optiok_fieldtype_image •/ 

«if defined (EW_CONriG_OPTIOH_FIELDTYPELDECIHM^UINT) \ 
I I defined (EW_C0NFIC_0PT10i?_FIELDTfPEwDEClMAl<_lNT)\ 
I I defined (EW_COHriG_OPTIOICFIELDTyPE_IMAGE) 

extern EwFieldTypeFronuf ewFieldFroiaDecimal ; 

#endif /• EW_CONFIC_OPTIOr?„FIELDTyPE_DECIKALw.UINT| INT i IMAGE •/ 

(tifdef EK_C0NFIG_0PT10H_FIELDTyPE_DECIKAL^ItJT 
extern EwFieldTypeTo_£ ewFieldToDecimallnt ; 

«endif /• EW_CONFIC_OPTIOICFIELDTyPE_DECIMAL_INT •/ 

#ifdef EW„C0NFIG_0PTIOIL.FIELDTyPE_HEX_INT 
extern EwFieldTypeTo^f ewFieldToHexInt; 
extern EwFieldTypeFronuf ewFieldFromHexInt; 
«endi£ /• EW_CONFIG_OPTION_FIELDTyPE_HEX_INT •/ 

«ifdcf EW_CONFIG.OPTIOH_FIELDTYPE_KEX_STR1NG 
extern EwFieldTypeTo_f ewFieldToHexString; 
extern EwFieldTypeFronuf ewFieldFromHexString; 
extern EwFieldTypeFree_f ewFieldPreeHexString; 
#endif /• EW„CONFIG_0PTI0I^„FIELDTyPE_HE)C_STRING •/ 

#ifd£f EW„CONFIG.OPTION_FIELDTypE_DOTTEDIP 
extern EwFieldTypeTo_f ewFieldToDottedIP; 
extern EwFieldTypeFronuf ewFieldFromDottedIP; 
#en(3if /♦ EW_CONFIG_OPTION_FIELDTyPE_D0TTEDIP •/ 

«ifde£ EW_C0NFIG_0PTIOW_FIELDTVPE_PECNET„IV 
extern EwFieldTypeTo_f ewFieldToDecnetIV; 
extern EwFieldTypeFronuf ewFieldFromDecnetlV; 
«endi£ /• EW_COHFIGUOPTION_FIELDTyPE_DEClfET_IV •/ 

«i f defined ( EWL-CONFI G_OPTI0N„FIELDTYPE_IEEE-WAC ) \ 
I t defined(EW_C0NFIG_0PTIOH_FIEU)TyPE_FDDI_JlAC)\ 
I I defined (EW_CONFIGL.0PTION_FIELDTyPIUSTD^C) 

extern EwFieldTypeFronuf ewFicldFroniMAC; 

Itendif /* EWUCONFIG_0PTI0H_FIEU)TyPE„IEEEiFDDI|STD_?lAC */ 

«if defined (EH_CONriG_OPTIOH_FIELDTyPE_IEEELWAC) \ 

1 1 defined (EV^C0NriC„0PTIONLFIEl'DTyPE_STD_>4AC) 
extern EwFieldTypeTo_f ewFieldTolEEEMAC: 

«endif /• EW_C0HF1Q„0PTI0H-FIELDTYPE„IEEE1STD_MAC ♦/ 

Itifdef EW CONFIC_OPTIOiq_FIELDTyPE_FDDI^C 
extern EwFieldTypeTouf ewFieldToFDDIMAC; 
«endif /* EW_C0NnC_0PTI0IO'IELDTyPE_FDDI_HAC •/ 

Sifdef EW_C0NFIG_OPTIOU„FIELDTyP^STD^C 

extern EwFieldTypeFronuf ewFieldFromStdMAC; 
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#endif /* EVL.COKFIGL.OPTIOH_FIELDTyPE;_STD_JlAC •/ 

«i£def EW_C0NFlG_OPTI0H„FIELDTyPELfILE 

extern EwFieldTypeFronuf ewFieldFromFile; 

extern BwFieldTypeFree_f ewFieldFreeFile; 

«endif /• EW_CONFIGL.OPTIOruriELDTyPEL.FILE •/ 

#i£def EMUCONFIO-OPTIOrCF'IELDTYPJL.OID 
extern EwFieldTypcTo_£ ewFieldToObjectID; 
extern EwFieldTypeFronL.f ewFieldFromObjectlD; 
extern EwFieldTypePre^f ewFieldFreeObjectiD; 

«eildif /• EW_CORFIG_OPT10H_FIELDTYPE_OID •/ 
typedef struct EwFonnFieldTable_jB 



{ 

uintf 

EwFi e 1 dTypeTo_f 
EwFi el dTypeFroin_f 
EwFieldTypeFree_f 
} EwFormFieidTable; 



£ield_size; 
•to_f ; 
*tTOT\_f; 



/• size of field •/ 

/* convert to HTML •/ 

/* convert from HTML •/ 

/* free dynamic pointer •/ 



Hifdef EW_DEFINE„FIELD_TyPEL.TABLE 

const EwFormFieldTable ewFormFieldTable [1 



{ 



{ sizeof (uint32) , ewFieldToDccimalUint, NULL, 



« ifdef EW_CONFIG_0PTron_FIELDTyPE_JlAlJI0 

, ( sizeof (int> , NULL, 

, { 0, ewFieldToRadioField, 
« else /• EW_CONFIC_OPTION_FIELDTYPE_RADIO •/ 

,{ 0, NULL, 

, { 0, NULL, 
t endif /* EW_CONFIGL.OPTI0ICFIELDTyPE,JlADI0 ♦/ 



evFi eldFromRadio , 
NULL, 

NULL, 
NULL, 



ifdef EW„CONFIG_0PTION_JIELDTyPE_SELECT_SINGLE 

, 1 sizeo?tint) , NULL, ewFi eldFromRadio, 

, I 0, ewFieldToSelectField, NULL, 

else /• EW_C0NFIG_0PTI0N_FIELDTYPE„SELECT_S1NCLE •/ 

, { 0, NULL, NULL, 

, { 0, NULL, NULL, 

endif /• EW_CONFIG_OPTION_FIELDTYPE_SELECT„SINGLE •/ 



NULL ) 



NULL 1 
NULL ) 

NULL ] 
NULL 1 



NULL J 
NULL ) 

NULL ) 
NULL ) 



« ifdef EW_C0NriG_0PT10N_FIELDTYPE_SELECT_MULTIPLE 

,{ sixeof (boolean) , ewFieldToSelectMulti, ewFieldFroniSelectMulti.NULL ) 
« else /* EW CONFICUOPTION_FIELDTyP^ELECT_WULTIPLE •/ 

, ( 0, NULL, NULL, NULL 1 

M endif /• ew_configl.option_fieldtype»select_>(ultiple •/ 

« ifdef EW_C0NFIQ_0PTIONJfIELDTYPE_CKECKB0X 

,t siieof (boolean) / ewFieldToChec)cbox, ewFieldFromChecXbox, NULL 1 
« else /♦ EW_CONriG_OPTIOH_FIELDTyPE_CHECKBOX •/ 

,10, NULL, NULL', NULL ) 

« endif /♦ E:v^_C0NFIG_OPTI0N_FIELDTyPE_CHECKB0X •/ 



« ifdef EVLC0NFIG_OPTION-FIELDTyPE_TEXT 
,t 8izeof(char *), ewFieldToText, 

fl else /• EVUC0NriG_0PTI0rO'IELDTyPE_TEXT ' 
,1 0, NULL, 

« endif /• EW_CONriG_OPTIOrCFIELDTyPELTEXT 



/ 



ewFieldFroinText, ewFieldFreeText ] 
NULL, NULL } 



« ifdef EW_CONFIG„OPTION_FIELDTyPE^IMAGE 

, t sizeo£{uint32) , NULL, ewFieldFronOJecimal, NULL) 

« else /* EW CONFlG_OPTION_FIELDTyPE-IMAGE •/ 

, { 0, NULL, NULL, NULL ) 
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t endif /• EW_C0KFIC_OPTI0H-FIEI*DTyPEL.rMAGE */ 

* # ifdef EW_CONFIG_OPTIOH„FIELIJTYP^ECIMAL_UINT 

,[ sixeof (uint32) , ewFieldToDecimaluint, ewFieldFromDecimal, NULL J 
$ else /• EW_CONFIGL.OPTION_FIELDTyPEJDECIMAL_UINT •/ 

, { 0, NULL, NULL, NULL ] 

« endif /« EW_CONFIG„OPTIOrUFIELDTyPE_DECIMAL_UINT */ 



H ifdef EW_CONFIG_OPTION_FIELDTyPELDECIMAL_INT 

,{ sizeof iuint32) , ewFieXdToDecimalint, ewFieldFroinDecimal, NULL } 
« else /• EW_C0NFIG_OPTI0N_FIELDTyPE_PECIMAL_INT •/ 

,{0. NULL, NULL, NULL ) 

« endif /* EW_C0HFIG_OPTI0N_FIELDTYPE^ECIMAL_INT •/ 



M ifdef EW_COKFIC_OPTION»^IELDTyPE_HE)L.INT 

,( Bizeof (uint32) / ewFieldToHexint , cwFieldFromHexint,' NULL 1 

M else /• EW_CONFIG_OPTI0N_FlELDTypEL.HEK_INT •/ 

, { 0, NULL, NULL, NULL } 

« endif /• EW_CONFIG_OPTION_FIELrTyPEL.HEX_INT •/ 



tl ifdef EW„CONFIG„OPTIOR_FIELDTYPE„KEX„STRING 

, I sizeoTtEwsFormFieldHexString) , ewFieldToHexString, ewFieldFromHexStrinq, 
ewFieldFreeHexString } 

# else /• EW_CONFIG_OPTION_FIELDTyPELHEX_STRING •/ 

, t 0, NULL, NULL, NULL 1 

« endif /• EW_C0NFICL_0PT10rCFIELDTYPE^EX_STRING •/ 

« ifdef EW_COHFIG_OPTION_FIELDT'yPE_J)OTTEDIP 

,t sizeof (uint32) , ewFieldToDottedlP, ewFieldFroirOSottedlP, NULL,) 

« else /• EW„C0NFIG_OPTIOrCFIELDTYPEL_DOTTEDIP */ 

.to, NULL, NULL, NULL ) 

# endif /• EW_C0NFIG„OPTION_FIELDTyPEL.D0TTEDIP •/ 



« ifdef EW_C0NFIG_OPTI0tsLFIELDTyP5_IEEILW^C 

,( 6, ewFieldToIEEEMAC, ewFieldFroinKAC, NULL ) 

« else /• EW_CONFIG_OPTIOJCFIELiynfPE„IEEEL>IAC •/ 

, ( 0, NULL, NULL, NULL ) 

« endif /• EW_CONFIG_OPTION_FIELDTyPE__IEEE_MAC •/ , 



« ifdef EW_CONFIG_OPTIOIi.FIELDTyPE_FDDI_>iAC 

6, ewFieldToFDDIMAC, ewFieldFronMAC, NULL ) 

<t else /* EW_CONFIG_OPTI0N_FIELDTyPE_FDDI^C */ 

,{ 0, NULL, NULL, NULL ) 

« endif /* EHUCONFIG_OPTION_FIELD'nrPE_FDDI_MAC */ 



« ifdef EW_C0NFIG_0PTI0N_FIELDTYPE_STD_J4AC 

6, ewFieldToIEEEMAC, ewFieldFrDniStdKAC, NULL ] 

It else /• EW_C0NFIG_OPTI0N„FIELIJT3fPE_STP^C •/ 

.[0, NULL, NULL, NULL } 

« endif /* EW_C0NFIGL-OPTION„FIELDTyPE-STD_>lAC •/ 

« ifdef EW_CONFIG_OPTIOICFIELDTyp^EaJET_IV 

,{ sizeof (uintl6> , ewFieldToDecnetIv, ewFieldFronOecnetlV, NULL J 

41 else /• EWLCONFIGLOPTIOtL-FIELDTlfPe^ECNET^IV •/ 

, I 0, NULL, NULL, NULL ) 

« endif /• EW„CONFICUOPTIOIi„FXELDTyPE_PECNET_IV •/ 

# ifdef EW_C0NFIG_OPTI0rUFIELDTyPE_FILE 

,{ sizeof (BwaFileHandle) , NULL, ewFieldFromFile,6wFieldFreeFile ) 

,1 sizeof (char *) , ewFieldToTcxt, ewFieldFromText,ewFieldFreeText ) 

M else /• lEW^CONFIG^OPTIONJ-IELDTYPE^FILE */ 

, { 0, NULL, NULL, NULL ) 

, { 0, NULL, NULL, NULL ) 

n endif /♦ EW_CONFIG„OPTI0N_FIELDTyPE„FILE */ 
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« Ifdcf EW„C0NF1G_0PTI01LJIELDTYPEL_0ID 

,1 sizco7(EwsFormFieldObjectID) , ewFieldToObjectID, ewFieldFromObject-D, 
ewFieldPreeObjectlD ] 
« else /• EW_COHFIG_OPTIOK_FIEUmf PELOID •/ 

, ( 0, NULL, HULL, HULL } 

# endif /♦ EVt.CONFICL,OPTI0rL.FIELDTYPEL_0ID •/ 



J; 

«else /* EVCDEFINIL_FOR«_FIEUL.TyPEL.TABLE •/ 
extern const EwFormFieldTable ewFormFieldTable [) ; 
#cndif /• EW_JDEFINE_FOR>L-FIELD_'nrPEL.TABLE •/ 

#cndif /• _EW_FORIUI •/ 
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* $Id: ew_imap.h,v 1.7 1997/05/21 21:55:48 ian Exp $ 

* Product: EmWeb 

* Release: INajne: $ 

* tCopyRiffht^ 

* ErnWeb image map definitions between server and generated code 
* 

V 

Itifndef _ew_imapj 
«define .^w_imap_JI 

^tinclude "ew_types .h" 

typedef struct EwImageMap_s 
I 

uint32 ul_;t; /♦ upper-left X coordinate •/ 

uint32 ul_y; /* upper-left Y coordinate ♦/ 

uint32 Ir_x; /* lower-right X coordinate */ 

uint32 lr_j^; /* lower-right V coordinate •/ 

const char •url; /• relative redirection URL •/ 

) EwimagcMap, • EwlmageMapP; 

typedef struct EwimageMapTable_s 
( 

const EwlmageMap •map_table; /• table of map entries •/ 
uintf map.entries; /♦ size of map_tablfi */ 

const char *default_url; /• default URL, or NULL if not specified •/ 
J EwlmageMapTable, * EwimageMapTableP; 

«endif /• „EW_IMAP_H •/ 
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CLAIMS 

What is claimed is: 

1. A method for providing a graphical user interface having dynamic elements, comprising 
the steps of: 

defming elements of the graphical user interface in at least one text document v^rittcn in a 
mark-up language; 

including at a location in the document a code tag containing a segment of application 
source code; 

serving the text document to a client which interprets the mark-up language; and 
when the location is encountered, serving to the client a sequence of characters derived 

from a result of executing a sequence of instructions represented by tlie segment of application 

source code. 

2. The method of claim 1 , further comprising the step of: 

including in the document at least one more code tag containing a segment of application 
source code. 

3. The method of claim 1 , wherein the step of defming further comprises the step of: 
providing a plurality of documents which collectively define the graphical user inlcrfacc; 

and 

storing the text document and the plurality of documents as files in a directory tree. 

4. The method of claim 3, further comprising the steps of: 

compiling the directory tree and the files therein into an archive including content 
sources; and 

decompiling a content source back into the text document before the step of serv^ing. 

5. A method for providing a graphical user interface having dynamic elements, comprising 
the steps of: 

defining elements of the graphical user interface in at least one text document v/ritten in a 
mark-up language; 
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including in the document a string identified by prototype tags; 

serving the text document to a prototyping client which interprets the mark-up language 
but does not recognize and does not display the prototype tags, but does display the string; and 

compiling the text document into a content source, omitting the prototype lags and the 
string identified thereby. 

6. The method of claim 5, further comprising the step of: 

including at a location in the document a code tag containing a segment of application 
source code, wherein the prototyping client does not recognize and does not display the code tag; 
and 

the step of further comprising including the segment of application source code in the 
content source. 

7. The method of claim 6, further comprising the steps of: 
decompiling the content source into a replica of the text document; 
serving the replica to a user client; and 

when the location is encountered in the replica, serving to the user client a character 
stream derived from a result generated by executing the segment of application source code. 

8. The method of claim 7, further comprising the steps of: 

including in the document at least one more code tag containing a segment of application 
source code; and 

including in the document at least one more string identified by code tags. 

9. A method for providing a graphical user interface having dynamic elements, comprising 
the steps of: 

defining elements of the graphical user interface in at least one text document written in a 
mark-up language; 

including at a location in the document a code tag containing a segment of application 
source code; 

including in the document a string identified by prototype tags; 
compiling the text document into a content source; 
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decompiling the content source into a repiica of the text document; 

serving the replica of the text document to a client which interprets the mark-up language; 

and 

when the location is encountered in the replica, serving to the client a character stream 
generated by executing the segment of application source code. 

1 0. The method of claim 9, further comprising the steps of: 

including in the document at least one more code tag containing a segment of application 
source code; and 

including in the document at least one more string identified by code tags. 

U . A software product recorded on a medium, the software product comprising a mark-up 
language compiler which can compile a mark-up language document into a data structure in a 
native application programming language, the compiler recognizing one or more code lags which 
designate included text as a segment of application source code to be saved in a file for 
compilation by a compiler of ihe native application programming language. 

12. A method for providing a graphical user interface having displayed forms for entry of 
data, comprising the steps of; 

defining elements of the graphical user interface in at least one text document written in a 

mark-up language; 

naming in the document a data item requested of a user and used by an application 
written in a native application progranmiing language; and 

compiling the text document into a content source including a data structure definition in 
the native application programming language for the named data item. 

13. The method of claim 1 2, wherein the text document is viewed using a prototype client 
during development and is viewed using a user client during use, further comprising tha steps of: 

naming the data item within a tag understood in the mark-up language for viewing by 
both the prototype client and the user client; and 
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including in the content source a definition of a function to provide a default value for the 
data item when the content source is served and a definition of a function to perform an 
application specific operation when the data item is returned by the user client. 

14. In a computer-based apparatus for developing a graphical user interface for an application, 
the apparatus including an editor which can manipulate a document written in a mark-up 
language and a viewer which can display a document written in the mark-up language, the 
apparatus further comprising: 

a mark-up language compiler which recognizes a code tag containing a source code 
fragment in a native application source code language, the code tag not otherwise part of the 
mark-up language, the compiler producing as an output a representation in the native application 
source code language of the document, including a copy of the source code fragment. 

1 5. The apparatus of claim 1 4, wherein the mark-up language compiler further recognizes 
begin and end prototype tags not otherwise part of the mark-up language, the output 
representation omitting the begin and end prototype tags and all content appearing therebetween 
in the document. 

16. A method for developing and prototyping graphic user interfaces for an application 
comprising the steps of; 

accessing an HTML file, 

encapsulating portions of said HTML and entering source code therein, 
producing a source module from said HTML with encapsulated portions, 
producing source code for a server, and 

cross compiling and linking said application, said source code module and said server 
thereby producing executable object code. 

17. The method of claim 1 6, further comprising the steps of: 
running said object code, 

executing said compiled encapsulated code when requested by a viewer, wherein said 
encapsulated code is associated with said application. 
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1 8. The method of claim 1 7, further comprising the steps of: 

converting data returned by execution of said compiled encapsulated code into a form 
displayabie by said viewer. 

1 9. The method of claim 18, wherein the data returned by executing said compiled 
encapsulated code changes over time as a result of changes within the application. 

20. A data structure fixed in a computer readable medium, the data structure for use in a 
computer system including a client and a server in communication with each other, the data 
structure comprising: 

cross-compiled, stored and linked, HTML files with encapsulated portions containing 
executable code associated with said application, server code, and application code, wherein said 
executable code is run when the HTML file is served thereby providing real time dynamic data 
associated with said application. 
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